How to Upgrade Odoo Community Edition

Odoo S.A. runs an upgrade service for Enterprise databases. Community Edition has no official upgrade tool, so moving a Community database to a new major version is up to you: by hand, with OpenUpgrade, or with an automated migration tool.

This guide covers the whole job: the difference between updating and upgrading, what changes between versions, how the options compare, and every step from the first backup to go-live. It links to a guide for each version pair, to fixes for the errors that stop real upgrades, and to the full preparation checklist.

The short answer

1. List your installed modules and decide what happens to each custom or third-party one.
2. Download a .zip backup (database plus filestore) and keep it untouched.
3. Run a test migration of a copy to the target version.
4. Restore the result on a staging server running the new version and check your workflows.
5. Fix what the test showed, then migrate a fresh backup of production in a maintenance window.
6. Restore it on the new server, run your checks, and let users back in.

Update or upgrade: which one do you need?

An update installs newer code of the same major version, for example the latest 18.0 revision. It brings bug and security fixes and keeps the database structure. How you update depends on how you installed Odoo:

# source install: pull the latest revision of your branch
cd /opt/odoo/odoo && git pull origin 18.0

# Debian/Ubuntu package
sudo apt-get update && sudo apt-get install --only-upgrade odoo

# Docker: pull the newer image of the same tag and recreate the container
docker pull odoo:18.0

Restart Odoo afterwards. If the new revision changed views or data files you rely on, load them with odoo -d yourdb -u all --stop-after-init, on a copy first.

An upgrade moves the database to a new major version, for example 18 to 19. New code alone cannot read the old database: models are renamed, modules merged, fields moved and data converted, and that takes migration scripts. The rest of this guide is about upgrades.

What changes in a major Odoo upgrade

Every major release restructures part of the database. The table counts what the OCU scripts handle for each step, besides the thousands of fields that are simply added or removed:

Counted from the Odoo source of each version and from the OCU migration mappings, step by step; Odoo’s internal test modules are left out because they never exist in a production database. Multi-step paths add up their steps.

The renames are the easy part to describe. The work is in the conversions: data that must change shape because a model was removed or redesigned. Inherited views also have to be reloaded from the new files, constraints the new version adds have to be met by old data, and records Odoo no longer ships have to be cleaned up without taking customer data with them.

Three ways to upgrade Odoo Community

By hand gives full control and needs deep knowledge of both versions. Odoo’s guide for upgrading customized databases is a starting point.

OpenUpgrade is the Odoo Community Association’s open-source migration project. You run it yourself, one version at a time, and module coverage varies per version. It is the only option for versions older than 15. Our OpenUpgrade vs OCU comparison goes into the differences.

OCU builds its migration scripts by comparing the source code of each pair of Odoo versions, adds hand-written steps for the data conversions, and runs them in isolated containers. You upload a backup and download the upgraded database. If your data cannot leave your network, the offline version runs the same engine on your own machine.

Step by step: from backup to go-live

1. Take stock of your installation

Note your exact version (Settings > General Settings, in the About section) and list installed apps under Apps with the Installed filter. Sort them into standard, third-party and custom. For every non-standard module, find out whether a version exists for your target release, whether a standard feature replaces it, or whether you can uninstall it. Uninstalling unused modules before the upgrade removes problems you would otherwise carry through every step.

2. Back up

Download a backup from the database manager (/web/database/manager) in .zip format, which contains the SQL dump and the filestore with your attachments. With pg_dump, remember to copy the filestore folder separately. Keep this file untouched; every trial runs on copies.

3. Run a test migration

Migrate a copy to the target version. With OCU, upload the backup; the source version is detected from the database, and if you skip versions the steps are chained. A test result is neutralized (outgoing mail and scheduled actions off) so it cannot contact customers. If the run fails, the error message tells you what to fix; our upgrade error guides cover the messages we see most.

4. Verify on staging

Set up a server with the target Odoo version and the new versions of your third-party and custom modules. Restore the migrated .zip through its database manager, then update those modules with -u. Check the figures you recorded before: trial balance, receivables and payables, stock valuation, a few known documents. Then walk through your daily flows: a quotation to invoice, a receipt and a delivery, a payment, whatever your team does every day.

5. Fix and repeat

Fix what the test showed, in the source database or in your modules, and run another test until the result is clean. Note how long the run took; it sizes your maintenance window.

6. Migrate production and switch over

Announce the downtime. Stop Odoo so nobody changes data, take a fresh backup, and migrate it as a production run. Restore the result on the new server, update your custom modules, run your checks, and let users back in. Keep the last backup of the old version: it is your way back if something unexpected shows up.

The Odoo migration checklist expands each of these steps into individual checks, from the module audit to the first week after go-live.

Guides for each version pair

Each guide lists what changes in that step and what to check afterwards.

One version at a time

• Migrate Odoo 15 to 16
• Migrate Odoo 16 to 17
• Migrate Odoo 17 to 18
• Migrate Odoo 18 to 19
• Migrate Odoo 19 to 20

Several versions in one run

• Migrate Odoo 16 to 18 (2 steps, chained automatically)
• Migrate Odoo 16 to 19 (3 steps, chained automatically)
• Migrate Odoo 17 to 19 (2 steps, chained automatically)
• Migrate Odoo 15 to 17 (2 steps, chained automatically)
• Migrate Odoo 15 to 18 (3 steps, chained automatically)
• Migrate Odoo 15 to 19 (4 steps, chained automatically)
• Migrate Odoo 18 to 20 (2 steps, chained automatically)
• Migrate Odoo 17 to 20 (3 steps, chained automatically)
• Migrate Odoo 16 to 20 (4 steps, chained automatically)
• Migrate Odoo 15 to 20 (5 steps, chained automatically)

On Odoo 10, 11, 12, 13 or 14? Read how to migrate older Odoo versions to 19 or 20. OCU starts at 15, and that guide explains how to get there.

Errors that stop Odoo upgrades

These messages come from real upgrades. Each guide explains the cause, how to fix it by hand, and what OCU does about it:

• Currently processing another module operation
• ForeignKeyViolation: key is not present in table
• ir_model_data_name_nospaces check constraint
• Time zone "Asia/Calcutta" not recognized
• Element cannot be located in parent view
• res.country.state: 'country_id, code' already exist
• UoM category should only have one reference unit
• Remove website on related partner
• TypeError: 'bool' has no len() in Odoo 19
• External ID not found in the system

For broader problem classes, such as module conflicts and view errors after an upgrade, see common Odoo migration problems.

Moving to Enterprise instead?

If you plan to switch from Community to Enterprise, Odoo’s own upgrade service handles that as part of an Enterprise subscription. OCU migrates Community to Community. The Community vs Enterprise migration guide compares both routes.

Frequently asked questions

How do I upgrade Odoo Community Edition to a new version?

Back up the database with its filestore, run a test migration of that backup to the target version, restore the result on a staging server running the new Odoo version with updated custom modules, check your daily workflows, then repeat the migration on a fresh backup during a maintenance window and switch production over. The migration itself can be done by hand, with OpenUpgrade, or with an automated tool such as OCU.

What is the difference between updating and upgrading Odoo?

An update installs a newer revision of the same major version, for example the latest 18.0 code, and keeps the database structure. An upgrade moves the database to a new major version, for example 18 to 19, and needs migration scripts that rename, merge and convert data.

Is there an official Odoo upgrade service for Community Edition?

No. Odoo S.A. offers its upgrade service (upgrade.odoo.com) for databases covered by an Enterprise subscription. Community Edition users upgrade themselves, use OpenUpgrade, or use a third-party tool like OCU.

Can I upgrade Odoo Community Edition without losing data?

Yes. A migration converts your existing records to the new structure: customers, invoices, products, stock moves and history all stay. Always keep the original backup untouched and verify a test result before upgrading production.

How long does an Odoo CE upgrade take?

The migration run usually takes minutes for databases up to about 1 GB; a 1 GB database went from 16 to 19 in about 17 minutes in our runs. The project around it, including checking the result and updating custom modules, takes days to weeks depending on how customized the system is.

Can I skip versions when upgrading Odoo?

The database has to pass through every major version, because each step’s scripts expect the previous version’s structure. A tool can chain the steps so you do it in one run: upload a 16 backup, choose 19, and OCU runs 16→17→18→19 internally.

How much does it cost to upgrade Odoo Community?

With OpenUpgrade or by hand, it costs your time or your partner’s. With OCU, test migrations are free and a production migration costs one credit (€99) for the whole chain, charged only when it succeeds. The offline version for running migrations on your own machine costs €990.

What happens to third-party modules during an upgrade?

Their code has to be replaced with versions written for the target release. During an OCU migration they stay installed with their data tables preserved, but their views are disabled so they cannot break the upgrade. Install the new versions afterwards.