Odoo Upgrade Guide: Moving to a New Version Safely

Odoo releases a new major version every year. Staying on an old version works for a while, until you need a feature, a security fix or a module that only exists for newer versions. Then the gap is bigger and the upgrade harder.

Here's how to upgrade without drama.

1. Inventory what you have

Before anything else, list:

• Every installed module, including standard, OCA, third-party and custom
• Which ones are actually used (check with users, and look for data)
• Any customisations made directly to core files (hopefully none)
• Integrations and what API calls they make

Uninstall what nobody uses. Fewer modules means a cheaper upgrade.

2. Check module availability on the target version

• Standard modules come with the new version, sometimes renamed or merged
• OCA modules: check the target version branch in each OCA repository
• Third-party apps: check the App Store or ask the vendor
• Custom modules: need porting by your developers

Some modules won't be available yet. Decide whether to wait, replace them or port them yourself.

3. Choose the upgrade route

Enterprise: Odoo's upgrade service migrates the standard data. You upload a database copy and get back an upgraded test database. Custom modules are your responsibility.

Community: The OCA's OpenUpgrade project provides migration scripts for standard modules, usually one version at a time. Coverage varies by module, so check its status.

4. Port custom modules

Each custom module needs updating for API changes in the new version: changes to the ORM, views, JavaScript framework and sometimes data models. Data migration scripts may be needed if fields have moved.

This is also the time to reconsider customisations. Some may now be covered by standard features.

5. Test in cycles

Run at least two test upgrades:

1. Technical test. Does the database upgrade? Do modules install? Do scheduled actions run?
2. Functional test. Key users run their real processes on the upgraded copy: quote to cash, procure to pay, manufacturing, month-end
3. Rehearsal. A timed run of the full cutover on a fresh copy of production

Track issues in a shared list. Fix, re-upgrade, retest.

6. Check reports and documents

Invoices, delivery notes and custom reports often change layout between versions. Print each one from the test system and compare.

7. Integrations

Test every integration end to end: eCommerce, marketplaces, shipping, payment providers, EDI. API behaviour changes between versions more than people expect.

8. Cutover

• Pick a quiet period, not month-end
• Freeze configuration changes a week before
• Take a full backup (database and filestore)
• Run the upgrade, smoke-test key flows, then open to users
• Have a rollback plan and a decision deadline

9. Hypercare

Expect a burst of small issues in the first week: a missing filter, a changed menu, a report quirk. Keep developers available.

Make the next upgrade easier

• Keep customisations in small, well-documented modules
• Avoid overriding core methods where possible
• Keep a customisation register
• Upgrade every one to two versions instead of every five

Moving to the latest release? The Odoo 20 upgrade checklist lists its breaking changes. Our Odoo migration service handles upgrades for Community and Enterprise. See also the ERP data migration guide.