binary

Any binary field that does not pick a specialized widget such as image or pdf_viewer renders through this one. Empty, it offers an upload button that opens the file picker. Filled, it shows the file's name with download and clear controls. The upload reads the file in the browser and stores it on the record as base64; the download streams it back through Odoo's /web/content controller, or straight from memory when the file was just uploaded and the record is not saved yet.

Its heavy users in core are the localization and compliance modules, where signed XML files, government submissions and certificates are stored on records: Spanish TicketBAI, Hungarian EDI, Egyptian ETA. Which is fitting, because those are exactly the files nobody can afford to lose to a mislabeled download.

The binary widget itself never causes project pain. The filename does. A binary column in the database stores bytes, not a name, so Odoo keeps the name in a second char field, and the two are only connected when the view says so. Skip that wiring and your users download files called document with no extension, or stare at a field that reads 108.55 Kb where a contract name should be.

For a team evaluating whether files belong on records at all: single file per record with a known meaning, like a signed contract on a subscription or a submission receipt on an invoice, is what this widget is for. Piles of loosely related documents belong in the chatter's attachments or a many2many_binary field instead, where each file keeps its own identity. Deciding that boundary early keeps document handling from sprawling across half your models.

Odoo Studio (Enterprise) creates the whole arrangement correctly.

1. Open the form in Studio.

2. Drag a File field from the Add a field panel onto the form. Studio creates the binary field and handles the filename wiring for you.

3. In Properties, you can switch the Widget to Image, PDF Viewer or Sign if the file has a known type; the plain File widget is this page's widget.

4. Set Required or conditional visibility as needed, like any field.

Studio covers creating the field. The restrictions live in XML:

Limiting what can be picked takes options="{'accepted_file_extensions': '.pdf,.xml'}". There is no Studio control for it.

Enforcing the type takes allowed_mime_type, and even that is a browser side check, not validation. A hard guarantee needs a server side constraint on the model, which is developer work.

Wiring a filename onto an existing hand built field means adding the companion char field and the filename attribute in the view. Studio only does this automatically for fields it created itself.

The canonical pair: binary plus filename

<field name="contract_file" widget="binary" filename="contract_filename"/>
<field name="contract_filename" invisible="1"/>

The second line matters: the filename field must be present in the view, invisible is fine, or the name cannot be saved on upload.

The model side of that pair

contract_file = fields.Binary(string="Contract")
contract_filename = fields.Char(string="Contract Filename")

Restricting the picker to PDFs and XML

<field name="edi_file"
       filename="edi_filename"
       options="{'accepted_file_extensions': '.pdf,.xml', 'allowed_mime_type': 'application/pdf,text/xml'}"/>

Why you see "108.55 Kb" instead of a name. When no filename attribute is set, the widget's display falls back to the field's own value when that value is a string. For a saved record, Odoo does not send the binary content to list and form reads, it sends a human readable size placeholder, and that placeholder is what gets displayed and even used as the download name. Every report of "my field shows a file size instead of the file" traces back to this fallback.

The silent filename drop. On upload, the widget writes the file's name into the companion field only if that field exists among the record's loaded fields, meaning it is present somewhere in the view. A correct filename attribute pointing at a real model field still loses the name silently when the field was never added to the arch. The invisible line in the example above is the fix.

The 255 byte cap. The source defines MAX_FILENAME_SIZE_BYTES = 0xFF, matching the filename limit of Linux, Windows and macOS filesystems, and slices the displayed name accordingly, with the comparison done at base64 length. Absurdly long names are truncated for display rather than rejected.

Downloads pick their source. getDownloadData checks whether the current value is a real payload or the size placeholder: fresh uploads on unsaved records download from the in memory base64, saved records stream from the server. That is why a just uploaded file downloads fine before you ever hit Save.

Odoo 20 is expected at Odoo Experience in Brussels, 24 to 26 September 2026. These findings are read from the public development branch, which can change until feature freeze, and this page will be re-verified against the release.

One new option appears: use_replace_button. With it enabled and no filename available, the widget suppresses the raw value fallback, so instead of the 108.55 Kb placeholder users get a clean replace affordance. It is an opt in fix for exactly the fallback quirk described in the deep dive.

Everything else is cosmetic or internal: props declarations migrate to the new schema system, and the behavior of uploads, downloads, the filename cap and both existing options is unchanged in the diff.

If your Odoo 18 or 19 views lean on binary fields for compliance documents, an upgrade assessment can confirm none of your filename wiring breaks in the jump.