Migrating Odoo — whether upgrading versions or moving between hosting platforms — is one of the highest-risk operations in an ERP lifecycle. A failed migration can cause data loss, extended downtime, and disrupted business operations. This guide covers the practical steps for planning and executing both types of migration so you can minimize risk and maintain continuity.
Odoo migrations fall into three broad categories, each with its own challenges and requirements:
Moving from one major version to the next (e.g., 17 to 18, or 18 to 19). Odoo releases a new major version annually, and each version introduces database schema changes, API modifications, and frontend framework updates. Version upgrades require compatibility testing for all installed modules, including custom development.
Moving your Odoo instance between hosting environments — for example, from Odoo.sh to a self-hosted server, from a VPS to a dedicated server, or from an on-premise installation to a cloud provider. The Odoo application and database remain the same version, but the infrastructure, networking, and system dependencies change.
Importing data from another ERP system into Odoo. This involves mapping data structures, transforming formats, cleaning legacy data, and validating imports. While not an Odoo-to-Odoo migration, it follows similar principles of planning, testing, and cutover.
Odoo releases a new major version every year, typically in October. Each version is supported for approximately three years with security patches. Understanding the upgrade lifecycle helps you plan timing and resource allocation.
Standard modules are handled by Odoo's official upgrade service, which processes database schema transformations and data migrations. However, custom modules — and any third-party modules not in the core — require manual adaptation. The three areas that typically change between versions are:
Before starting a production upgrade, always request an upgraded test database from Odoo's upgrade service. This gives you a working instance of your data on the target version, allowing you to test custom modules and verify functionality before touching production.
Custom modules are the most common source of upgrade failures. Preparation should begin well before the upgrade window:
Stop new feature development at least two to four weeks before the planned upgrade. Adding new code during this period creates a moving target and increases the chance of regressions. Focus on stabilizing and testing existing functionality.
Review your custom modules against the target version's release notes. Look for deprecated methods, changed field types, and removed features. Odoo publishes migration guides with each release that document breaking changes.
Install your custom modules on a fresh database of the target version. This reveals installation errors, view definitions that no longer parse, and model inheritance conflicts. Fix these before attempting to migrate production data.
If your custom modules lack test coverage, now is the time to add it. Automated tests catch regressions that manual testing misses, especially in complex business logic. Run the full test suite on the target version before and after the data migration.
Every custom module is a maintenance burden during upgrades. If a customization is no longer used or can be replaced by a standard feature in the target version, remove it. Less custom code means a simpler, faster upgrade.
Follow this step-by-step workflow to minimize risk during a version upgrade:
Moving Odoo between hosting platforms involves transferring the database, filestore, configuration, and any custom system dependencies. The process varies depending on the source and destination:
Download a complete backup from the Odoo.sh dashboard, which includes the database dump and filestore. Set up a new server with the same Odoo version, restore the database, copy the filestore to the appropriate path, and configure the Odoo configuration file. Update DNS records to point to the new server. Odoo.sh does not provide SSH access to the underlying server, so the backup-and-restore approach is the only migration path.
Export your database with pg_dump and compress the filestore directory. Provide these to your hosting provider, who restores them on the managed infrastructure. The provider handles server provisioning, PostgreSQL configuration, and SSL setup. You typically get SSH access to manage your Odoo instance while the provider handles the underlying infrastructure.
Similar to the managed hosting path, but you handle all infrastructure setup on the new server. Ensure the target server has matching or compatible versions of Python, PostgreSQL, and system libraries. Test the restored instance thoroughly before switching DNS.
Key considerations for any hosting migration include database size (large databases take longer to transfer and restore), filestore size, DNS TTL settings (lower TTL before migration to speed up the switchover), and SSL certificates (provision new certificates on the target server before switching traffic).
A rollback plan is your safety net. Before any production cutover, document exactly how to revert to the previous state:
These are the mistakes that cause the most problems during migrations:
Running the upgrade directly on production without testing on staging is the most common cause of migration failures. Always test first.
Standard modules may upgrade cleanly, but custom modules often break. Budget time for adapting custom code, not just testing it.
Migrations take longer than expected. Schedule cutover during periods of lowest activity, and communicate the downtime window generously.
After restoring on a new server, DNS must point to the new IP, and SSL certificates must be valid for the domain. Both are easy to overlook in the rush of a migration.
Migration planning is easier with the right infrastructure and staging tools in place.