Introduction
If you have ever uploaded a product photo, set a company logo, or attached a profile picture to an employee record in Odoo, you have already interacted with an Image field. It is one of the most visual field types in the Odoo data model, and it shows up in more places than most users realize.
For business users, it mostly just works. You click a button, upload a file, and the image appears on the record. But for consultants and developers configuring Odoo, there is quite a bit happening underneath. The Image field has its own storage mechanism, automatic resizing behavior, and some nuances that are worth understanding before you start adding image fields to custom models.
This guide covers what the Image field stores, how it behaves in the Odoo framework, how to add it using Odoo Studio or Python, and practical examples from real business workflows.
What is the Image Field in Odoo
The Image field is a dedicated field type in the Odoo ORM, introduced as fields.Image in Odoo 13. Before that version, developers used a fields.Binary field combined with the image widget to achieve the same result. Today, the Image field type handles the full lifecycle of image storage, including automatic resizing, on its own.
Under the hood, the Image field stores binary data encoded in base64. In the PostgreSQL database, this data is saved as a bytea column or, more commonly in modern Odoo versions, as a file attachment linked to the record. This attachment-based storage keeps the main database tables lighter and allows Odoo to serve images efficiently via its attachment URL system.
How it looks in the interface
In a form view, an Image field renders as a clickable image placeholder. Users can upload a file directly from their computer, and in some cases they can also paste a URL. The field shows a thumbnail preview directly on the form, which makes it easy to spot at a glance.
In list views, Image fields are rarely shown because thumbnails in lists can slow down loading. However, they can be displayed in kanban views, where small card-based layouts benefit from visual indicators like product photos or contact avatars.
Odoo field types: Image vs Binary
It is worth knowing the distinction between the two. A Binary field stores any file type: PDFs, spreadsheets, zip files, and so on. The Image field is specifically designed for image files. It applies automatic resizing on save, enforces image-specific validation, and renders correctly with the image widget by default. If you are storing non-image files, use Binary. If you are storing photos or logos, use Image.
How the Field Works
When a user uploads an image to an Image field, Odoo does not simply store the raw file as-is. It processes the image first.
Automatic resizing
The fields.Image declaration accepts max_width and max_height parameters. If the uploaded image exceeds those dimensions, Odoo resizes it automatically while preserving the aspect ratio. This happens transparently on save, so users never need to think about it.
The default maximum size for a standard Image field is 1920 pixels on the longest side. This is why the field is often named image_1920 on standard Odoo models like product.template or res.partner.
Image size variants
On built-in Odoo models, you will often see a pattern of related image fields alongside the main one: image_1920, image_1024, image_512, image_256, and image_128. These are separate fields.Image fields defined as related fields pointing back to the primary image, each with different size limits.
This approach lets Odoo serve the right image size depending on context. A product listing page fetches the small image_128 thumbnail to keep page loads fast. A product detail page fetches the full image_1920 for a sharper display. For custom models, you may or may not need this multi-size pattern depending on how and where the image will be displayed.
Storage as attachments
By default, Image fields store their data as Odoo file attachments. This means the binary content lives in the ir.attachment model rather than directly in the record table. The record holds a reference to the attachment.
Practically, this keeps the main database tables lean. It also means images are accessible via predictable URLs like /web/image/product.template/42/image_1920, which is the pattern used in website pages, email templates, and API responses.
Access control
Image fields respect the same access rules as the rest of the record. If a user does not have read access to a product, they cannot retrieve its image either. This is handled automatically by the Odoo security layer, which is something worth knowing when building customer-facing portals or public website pages.
Business Use Cases
The Image field appears in almost every Odoo module. Here are some of the most common real-world applications.
1. Product catalog (Sales and Inventory)
Product images are probably the most visible use of Image fields in Odoo. Every product template has an image_1920 field, and those images appear in the webshop, on sales order PDFs, in point-of-sale screens, and in picking operations on mobile devices.
Companies with large catalogs often use the API to bulk-upload product images rather than adding them one by one through the interface. The Image field accepts base64-encoded binary data, so it is straightforward to upload images programmatically via XML-RPC or JSON-RPC.
2. Customer and supplier logos (CRM and Purchasing)
The res.partner model has an Image field used for contact photos and company logos. This image shows up in the partner form, in the chatter area, and in CRM kanban cards. For sales teams working with many accounts, having logos on contact records makes it easier to visually navigate through the customer list.
3. Employee photos (HR)
The hr.employee model stores an employee photo in an Image field. This photo appears in the employee directory, on payslips in some configurations, and in the Odoo Discuss module next to messages. HR teams often load these photos when onboarding a large batch of new employees, again using bulk import or the API.
4. Equipment and asset photos (Maintenance)
The Maintenance module allows attaching an image to equipment records. Field technicians find it useful to have a photo of the machine directly on the maintenance order, so they can quickly confirm they are working on the right piece of equipment before starting a repair.
5. Custom inspection or quality forms
Some companies build custom models in Odoo for quality checks, site inspections, or delivery confirmations. Adding an Image field to these models lets field staff attach a photo as evidence directly on the record. This is a common Odoo customization pattern and works well whether the field is added through Odoo Studio or directly in Python code.
Creating or Customizing the Field
There are two main ways to add an Image field to an Odoo model: through Odoo Studio without writing code, or through Python development for more control.
Using Odoo Studio
Odoo Studio is the built-in no-code customization tool. To add an Image field using Studio, open the relevant app, activate Studio from the top menu, and navigate to the form view where you want the field to appear.
In the field panel on the left, drag an Image field onto the form. Studio will prompt you to give it a label and will automatically create the underlying field on the model. This is the recommended approach for business users and functional consultants who want to create fields in Odoo without involving a developer.
Fields created through Studio are prefixed with x_studio_ by convention, for example x_studio_site_photo. They behave exactly like native Image fields in terms of storage and display.
Using Python (Odoo development)
For technical customizations, you define Image fields directly in a Python model file. Here is a basic example of how a developer would add an Image field to a custom model:
from odoo import models, fields
class SiteInspection(models.Model):
_name = 'site.inspection'
_description = 'Site Inspection'
name = fields.Char(string='Reference', required=True)
photo = fields.Image(
string='Site Photo',
max_width=1920,
max_height=1920,
)
photo_128 = fields.Image(
related='photo',
max_width=128,
max_height=128,
store=True,
string='Thumbnail',
)The max_width and max_height parameters tell Odoo to cap the stored size at 1920 pixels. The second field, photo_128, is a related field that stores a smaller version for use in kanban cards or list views. This is the standard Odoo development pattern for handling multiple image sizes on a single record.
Adding the field to a view
Once the field exists on the model, it needs to be added to a view to be visible in the interface. In a form view XML, you display an Image field using the widget="image" attribute:
<field name="photo" widget="image" class="oe_avatar"/>The oe_avatar class positions it as a circular avatar in the top-left corner of the form, which is the standard Odoo style. You can also use it without the class to place it inline within a form layout.
Best Practices
Here are the recommendations we give clients when working with Image fields in Odoo.
Set realistic size limits
The default 1920 pixel limit is appropriate for most use cases. Avoid increasing it unless you have a strong reason, such as very high-resolution product photography for print. Larger images mean larger attachments, which affects database size and page load performance.
Create a thumbnail variant for lists and kanban
If you are displaying the image in list views or kanban cards, define a separate small-size related field capped at 128 or 256 pixels. Fetching a 128-pixel thumbnail is much faster than loading the full 1920-pixel image for every card on screen.
Use the API for bulk image uploads
When you need to load images for hundreds or thousands of records, do not do it manually through the interface. Use the Odoo XML-RPC or JSON-RPC API to write base64-encoded image data directly to the field. This is much faster and can be automated in a script. The Odoo developer guide covers this pattern well.
Compress images before uploading
Even though Odoo resizes images automatically, it does not always compress them aggressively. A 5 MB JPEG resized to 1920 pixels may still be several hundred kilobytes. Pre-compressing images before uploading keeps attachment sizes manageable, particularly when dealing with large product catalogs.
Avoid Image fields in frequently queried list views
Including an Image field in a list view column forces Odoo to fetch binary data for every visible row. This can make list views noticeably slower. Use a small thumbnail if you really need a visual in a list, and keep the full-size image for the form view only.
Common Pitfalls
These are the mistakes we see most often when teams start working with Image fields in Odoo.
Confusing Binary and Image fields
A Binary field without the image widget will render as a download button, not as an image preview. If you want a proper image display, you need either a fields.Image field type or a fields.Binary with widget="image" explicitly set in the view. Forgetting this is a common source of confusion, especially when working on older Odoo versions.
Not thinking about image size variants early enough
Adding a single large Image field is easy, but if you later realize you need smaller versions for a kanban view or a website listing, adding those related fields requires a database migration if you are in a custom module. Planning the size variants upfront saves headaches later.
Storing images directly instead of using attachments
In very old Odoo versions or poorly configured instances, binary data could be stored directly in the database column rather than as attachments. This inflates the size of the main tables significantly and slows down unrelated queries. Make sure your Odoo instance is configured to use file storage or S3-compatible storage for attachments.
Using Image fields as document storage
Some users try to store scanned documents or screenshots in Image fields. While technically possible, it is not the right tool. For document management, use the Odoo Documents module or a Binary field with a file download widget. Image fields are designed for photos and logos, not for storing multi-page documents.
Forgetting access rules on public pages
If you display image URLs on a public website or in a portal and the underlying record is not accessible to public users, the image will return a 404 error. When building website pages or customer portals, always check that the image URL is accessible to the expected audience.
Conclusion
The Image field is one of the simplest field types to use on the surface, but it has enough depth to trip up teams that do not plan ahead. Understanding how Odoo handles resizing, storage as attachments, and the multi-size variant pattern will save you time when building or configuring models that need visual data.
For business users, knowing that images are stored securely on the record and accessible through predictable URLs helps when setting up website pages or portal views. For developers, the combination of fields.Image with related thumbnail fields is the standard Odoo pattern, and it is worth getting comfortable with early.
Whether you are adding a product photo to your catalog, attaching a site inspection photo to a custom model, or building a customer portal that displays contact logos, the Image field gives you a clean and integrated way to handle visual data inside the Odoo data model.
Need Help with Your Odoo Implementation?
At Dasolo, we help companies implement, customize, and optimize Odoo across all modules and versions. Whether you need to configure fields on standard models, build custom modules from scratch, or migrate data from a legacy system, we work hands-on with your team to get Odoo running the way your business actually works.
If you have questions about your Odoo setup or want to explore what is possible with the platform, reach out to us. We are happy to help.