Introduction
An Odoo upgrade is not complete because the new login screen opens. Orders must still generate the correct deliveries and invoices, stock valuation must reconcile, and custom approvals must work with the right data.
That is why an Odoo version upgrade is both a database migration and an application project. Odoo must convert standard data to the target version, while the implementation team adapts custom modules, checks integrations, restores the correct filestore and validates complete business processes.
This guide explains the real upgrade methods for Odoo Online, Odoo.sh, Enterprise on-premise and Community installations. It also covers custom-module migration, data-loss risks, testing, production cutover and rollback.
What Is an Odoo Version Upgrade?
An Odoo version upgrade moves an existing database from one major Odoo release to a newer one for example, from Odoo 16 to Odoo 19. The objective is to preserve valid business records while adapting the database schema, standard applications and custom code to the target release.
It is useful to separate four commonly confused projects:
| Project | What changes? | What usually stays? |
|---|---|---|
| Version upgrade | Odoo database schema, standard apps and compatible custom code | Business history and core configuration |
| Module update | One or more modules within the same Odoo version | Odoo major version |
| Hosting migration | Server or hosting platform | Usually the Odoo version and database structure |
| Reimplementation | Processes, configuration and often the data model | Only selected data and requirements |
The term Odoo version migration is often used for a version upgrade. However, migrating from SAP, Dynamics or another ERP into Odoo is a different project involving source-data extraction, mapping and a new implementation.
Why and When Should You Upgrade Odoo?
An upgrade may be appropriate when the current release is approaching the end of support or newer standard features could replace customizations. Operating systems, PostgreSQL, external APIs and third-party modules can also become harder to maintain around an older release.
Do not select a go-live date based only on the new version's features. First confirm:
- whether the current database is Enterprise or Community
- where it is hosted
- whether critical third-party modules support the target version
- which custom features can be removed, replaced or must be migrated
- how much historical data must remain operational
- whether there is time for testing, training and a cutover rehearsal.
If the existing configuration and data remain useful, upgrading is usually more practical than rebuilding. A fresh implementation may be better when the company wants to redesign its processes, remove years of obsolete customization or migrate only selected history.
Odoo Enterprise vs Community Upgrade Methods
The correct Odoo database migration method depends mainly on the edition and hosting platform.
| Environment | Typical upgrade approach | Main consideration |
|---|---|---|
| Odoo Online | Request test and production upgrades through Odoo's database manager | Custom Python modules are not supported on Odoo Online |
| Odoo.sh | Use the integrated upgrade workflow, staging builds and Git branches | Custom code must be made compatible with the target version |
| Enterprise on-premise | Submit a database copy to Odoo's official upgrade platform, then deploy the upgraded database | The target server, custom code and original filestore must be prepared |
| Community on-premise | Use an open-source framework such as OCA OpenUpgrade, or develop a controlled custom migration | Coverage and scripts must be checked for every installed module and version step |
| Fresh implementation | Configure a new database and selectively import master, opening and historical data | Historical continuity, references and integrations need explicit mapping |
Odoo's official upgrade platform converts the standard Enterprise database. Independently developed modules still require project work.
How the Official Odoo Enterprise Upgrade Service Works
Odoo provides an official upgrade process for eligible Enterprise databases. The exact interface varies by hosting platform, but a controlled project follows the same broad sequence:
- Create a complete and restorable production backup.
- Request an upgraded test database for the chosen target version.
- Restore or open that converted database in a target-version test environment.
- Install compatible custom code and run required custom migration scripts.
- Reconnect a safe copy of the filestore and non-production integrations.
- Validate the database technically and functionally.
- Fix issues and request another test upgrade when necessary.
- Rehearse the production cutover before requesting the final production upgrade.
A successful conversion does not prove that a custom approval, connector or report produces the correct result.
Odoo Online
For Odoo Online, the database manager is used to request test and production upgrades. Because Odoo Online does not allow custom Python modules, review configuration, Studio changes, standard app behavior and external integrations.
Enterprise On-Premise
For an on-premise Enterprise installation, a database copy is submitted to the upgrade platform. The returned database must be deployed with the target Odoo code, compatible Enterprise modules and adapted custom add-ons.
Odoo's documentation highlights a filestore requirement: before testing a returned on-premise database, its filestore must be merged with or connected to the corresponding production-filestore copy. A database-only restore can make attachments, invoice PDFs and images appear missing.
How Does an Odoo.sh Upgrade Work?
Odoo.sh is integrated with Odoo's upgrade platform, but this automation does not remove the need to migrate custom code.
A typical Odoo.sh upgrade workflow is:
- Review dependencies, custom modules and third-party apps in the Git repository.
- Use the Odoo.sh upgrade interface to obtain an upgraded test database.
- Prepare a target-version branch and adapt custom Python, XML, JavaScript and data files.
- Build the branch in staging with the upgraded database.
- Test installation logs, scheduled jobs, integrations and complete user workflows.
- Commit fixes and rebuild until the test results are acceptable.
- Rehearse the production procedure and schedule the final upgrade.
- Freeze data entry, take the final backup, run the production upgrade and deploy the validated code.
Staging allows the team to test target-version code against a production-like database without changing the live system. Use sandbox credentials or disable external services so tests do not send real emails, charge cards or create live shipments.
How Does OpenUpgrade Work for Odoo Community?
OCA OpenUpgrade is an open-source migration project for Odoo Community databases. It combines a framework with version-specific migration scripts that handle changes such as renamed fields, renamed models, changed XML IDs, module restructuring and transformed values.
OpenUpgrade is not a one-click equivalent of the Enterprise service. Coverage varies by version and module; a branch may exist while a required script remains incomplete.
Before using OpenUpgrade:
- inventory every standard, OCA, third-party and custom module
- check migration coverage for each major version step
- review database-specific changes and previous customizations
- run the migration only on isolated copies
- read migration logs and resolve warnings rather than ignoring them
- reconcile the result before continuing to the next version.
For a multi-version move such as Odoo 16 to Odoo 19, Community work is normally validated per major version step. A final login screen does not prove every data transformation succeeded.
How to Upgrade Custom Odoo Modules
An Odoo custom module migration has two connected parts: adapting the source code and preserving the existing data created by that code.
1. Update the module code
Review the manifest, dependencies, Python APIs, ORM behavior, XML views, security, reports, controllers, JavaScript and tests. Some changes prevent loading; subtler ones allow installation but produce incorrect results.
2. Map database changes
If a custom field or model is renamed, changing only the Python name can leave existing values in an old column or table. The migration needs an explicit mapping. Similar care is required when a selection value changes, a model moves to another module, an XML ID changes or multiple fields are consolidated.
Odoo supports upgrade scripts that can run in pre, post and end-migration phases. These scripts can rename database elements before a module loads, transform values after the new schema is available and complete cleanup or consistency work at the end.
3. Test behavior, not only installation
A green build is only a starting point. Verify calculations, access rules, approvals, emails, reports and failure paths using representative records. Test both old migrated records and new records created in the target version.
Database Migration and Data-Loss Prevention
Odoo stores business records in PostgreSQL. Attachments have database records, while their binary content may be stored in the filestore or an external storage service. Custom-module data can also depend on model names, fields, XML IDs and relational links. This is why database and file backups must be treated as one recoverable set.
| Potential issue | What can happen | Recommended safeguard |
|---|---|---|
| Renamed field | Values remain in an old column or are no longer exposed by the new model | Use a migration script and compare representative values |
| Removed or renamed model | Historical records become inaccessible or links break | Define an explicit model and relation mapping |
| Changed XML ID | Configuration or references point to the wrong record | Rename or remap the XML ID in a controlled script |
| Filestore mismatch | Attachments, PDFs and images appear missing | Restore the matching database and filestore together |
| Changed accounting or valuation logic | Reports differ from the original system | Reconcile trial balance, taxes, aged items, inventory and valuation |
| Missing third-party module | Its models, menus or records cannot be used | Confirm target-version availability before conversion |
| Failed script | A self-managed database may be left partially changed | Run on disposable copies and restore from a verified backup |
| Multi-company rule error | Records appear under the wrong company or become inaccessible | Test record counts, company ownership and user access |
Record counts are a warning signal, not proof. Because version changes may merge, split or archive records, combine counts with control totals, relationship checks and sampled comparisons.
Example: Upgrading Odoo 16 to Odoo 19
Consider a manufacturer running Odoo 16 Enterprise on-premise with Sales, Purchase, Inventory, Manufacturing, Accounting and a custom quality module.
Phase 1: Discovery
The team inventories modules, database size, filestore size, integrations, cron jobs and custom reports. It confirms that the quality module adds inspection records linked to manufacturing orders and stock lots. Those relations become explicit migration requirements.
Phase 2: First test conversion
A production copy is backed up and submitted through the official service for an Odoo 19 test upgrade. The returned database is restored in an isolated Odoo 19 environment, and the matching filestore is connected. All outgoing email and live integrations remain disabled.
Phase 3: Custom-code and data migration
Developers port the quality module to Odoo 19. They update its Python and XML code, map any renamed fields and create scripts to preserve inspections and their links. The target branch is installed against the upgraded database, not just an empty database.
Phase 4: Technical and business validation
The team reviews server logs and tests user permissions, scheduled actions and API exchanges. Business users then receive materials, manufacture a batch, record quality results, move finished stock, deliver an order and post the invoice. They also test rejected quality checks, partial production and cancelled transactions.
Accounting compares the trial balance, aged receivables and payables, taxes, inventory valuation and selected journal entries with the Odoo 16 baseline. Operations compare products, lots, bills of materials, open orders and stock quantities.
Phase 5: Rehearsal and production cutover
After fixes, the team repeats the process using a fresh production copy and records the duration of every step. At go-live, users stop data entry, the final database and filestore are backed up, the production upgrade is requested, validated code is deployed, and smoke tests are completed before users return.
If a critical issue cannot be corrected within the agreed window, the rollback plan restores the pre-upgrade database and its matching filestore and returns the application code and integrations to the Odoo 16 state.
Common Odoo Upgrade Errors and Risks
The most common mistake is treating database conversion as the whole project. Other frequent problems include:
- installing target-version custom modules without migrating their historical data
- using a database dump with the wrong filestore
- ignoring warnings about missing modules or failed upgrade scripts
- testing only new records instead of migrated records
- allowing staging to contact live payment, email or shipping services
- validating totals without checking multi-company and access-rule behavior
- carrying obsolete customizations into the new release
- starting production without a timed rollback decision and restorable backup.
Every issue should have an owner, severity and acceptance decision. Cosmetic differences should not distract the team from blockers such as incorrect balances, missing attachments or broken order processing.
Pre-Upgrade and Post-Upgrade Checklist
Before the upgrade
- Confirm edition, hosting, source version and target version.
- Inventory standard, third-party, OCA, Studio and custom components.
- Choose the correct official, Odoo.sh or OpenUpgrade method.
- Back up and test restoration of both database and filestore.
- Record financial, stock and operational baseline totals.
- Prepare target-version code and migration scripts.
- Create business test cases and assign process owners.
- Disable or sandbox external services in test environments.
- Complete at least one fresh-data rehearsal.
- Approve the cutover, communication and rollback plan.
After the upgrade
- Review startup, module, migration and scheduled-action logs.
- Confirm users, companies, permissions and record rules.
- Reconcile accounting, stock, open transactions and sample records.
- Open representative attachments and generated reports.
- Test sales, purchasing, inventory, manufacturing and invoicing end to end.
- Verify integrations without creating duplicates.
- Monitor performance, queues, cron jobs and errors.
- Record user acceptance and keep the old environment protected until sign-off.
Frequently Asked Questions
1. Does Odoo's official upgrade service migrate custom modules?
It converts the standard Enterprise database, but independently developed modules and their custom data logic still require review, code adaptation and, where needed, migration scripts.
2. Is Odoo.sh automatically compatible with every custom module?
No. Odoo.sh integrates the database-upgrade and build workflow, but developers must make custom and third-party code compatible with the target release and test it against the upgraded database.
3. Can Odoo Community use the official Enterprise upgrade service?
Community projects generally use a suitable open-source or custom migration approach, such as OpenUpgrade. If the business is also moving to Enterprise, eligibility and the required conversion path should be confirmed with Odoo before planning the project.
4. Is OpenUpgrade complete for every module and version?
No. Check the project branch and coverage for every installed module and version step. Custom and less common modules may need additional scripts.
5. Will an Odoo upgrade preserve all attachments?
It can, but the correct filestore or external object storage must accompany the matching database. A database-only restore may preserve attachment records while leaving their files unavailable.
6. Can an Odoo upgrade be rolled back?
Rollback normally means restoring the complete pre-upgrade database and filestore and redeploying the previous code. It is not a downgrade of the already modified production database. Define the decision deadline before cutover.
7. How long does an Odoo version upgrade take?
The duration depends on the version gap, database and filestore size, module count, customization, integrations and user-testing scope. Estimate discovery, code migration, repeated test upgrades, reconciliation, rehearsal and deployment separately.
Conclusion
A reliable Odoo version upgrade combines the right migration method with careful custom-code work, data preservation and business validation. Odoo Online, Odoo.sh, Enterprise on-premise and Community databases do not follow identical paths, so the project must begin with the correct platform decision.
Protect the matching database and filestore, migrate custom data explicitly, test real transactions and rehearse the production cutover. These controls turn a technical conversion into an upgrade the business can trust.
If you need help assessing a customized database, adapting modules or planning a controlled move to a newer release, explore Browseinfo's Odoo Migration Services.
