Odoo 20 Upgrade Guide: How to Upgrade Your Database Safely

An Odoo 20 upgrade should be treated as a controlled migration project, not a version switch.

Odoo’s official process is deliberately test-first: request an upgraded test database, make custom modules compatible with the target version, test the upgraded system thoroughly, resolve discrepancies, rehearse the process, and only then schedule the production upgrade.

The database conversion is only one part of the project. A successful upgrade also has to preserve the business processes around that database: custom modules, integrations, reports, accounting behavior, websites, automations, permissions, payments, inventory flows and user workflows.

This guide explains how to plan that process for Odoo Online, Odoo.sh and on-premise deployments, and where custom Odoo projects require additional engineering.

Important: Odoo 20 is released, but target-version upgrade availability can depend on the source version, hosting model and the current state of Odoo’s upgrade tooling. Verify that your exact database can target Odoo 20 before committing to a production date.

The Odoo 20 upgrade process in seven steps

At a high level:

1. Audit the current database.
2. Freeze and challenge custom development.
3. Request an upgraded test database.
4. Upgrade custom modules and integration code.
5. Run functional, technical and data testing.
6. Rehearse the production cutover.
7. Upgrade production and validate immediately.

That sequence looks simple. The work inside steps 2–6 determines whether the upgrade is routine or disruptive.

First: understand what an Odoo “upgrade” actually is

Odoo distinguishes an upgrade from an ordinary software update.

An update keeps the database on the same major Odoo version while applying newer source-code revisions.

An upgrade changes the database so that its structure and contents are compatible with a newer major release. Odoo describes this operation as irreversible.

An upgrade also does not mean:

• changing from Community to Enterprise;
• changing hosting type;
• moving from another ERP to Odoo;
• cleaning existing business data;
• automatically rewriting every third-party or in-house custom module.

Those may be related projects, but they should not be hidden inside the upgrade scope.

Step 1 — Audit the database before requesting anything

Before touching the upgrade platform, create an inventory of what the production database actually contains.

At minimum, record:

Platform

• current Odoo version;
• target version;
• Community or Enterprise;
• Odoo Online, Odoo.sh or on-premise;
• PostgreSQL/infrastructure details where relevant.

Applications

• installed standard Odoo apps;
• Studio customizations;
• Odoo Apps/third-party modules;
• internally developed modules;
• modules inherited from a previous implementation partner.

Integrations

• mobile apps;
• customer/supplier portals;
• payment providers;
• shipping/carrier integrations;
• EDI;
• bank integrations;
• eCommerce marketplaces;
• attendance/biometric systems;
• external APIs and middleware;
• BI/data-warehouse connections;
• webhooks and scheduled synchronization jobs.

Custom behavior

• automated actions;
• server actions;
• scheduled actions;
• custom reports;
• custom email templates;
• custom access rules;
• custom views;
• JavaScript/Owl frontend changes;
• custom controllers/API endpoints;
• custom accounting, stock or manufacturing logic.

If you cannot answer “what is custom?” before the upgrade, you will have difficulty proving that the upgraded database behaves correctly afterward.

Step 2 — Freeze custom development and challenge it

Odoo’s customized-database guidance recommends stopping development during the upgrade process, except for necessary bug fixes.

There is a practical reason: every feature added to the old branch after migration work starts creates more code that must be reviewed, migrated and tested again.

But a code freeze is only half the step.

The more valuable exercise is to challenge each customization.

Ask:

• Does Odoo 20 now provide this functionality natively?
• Is the customization still used?
• Was it a workaround for a limitation that no longer exists?
• Can Studio or standard configuration now replace it?
• Does the custom module still justify its maintenance cost?
• Can two overlapping modules be consolidated?

A version upgrade is one of the best opportunities to reduce technical debt.

Migrating obsolete customization perfectly is still wasted engineering.

Step 3 — Request an upgraded test database

Do not make production your first complete test.

Odoo’s official upgrade process begins with an upgraded test database. You can request multiple test upgrades as the project progresses.

The exact workflow depends on hosting.

Odoo Online

For Odoo Online, the upgrade flow is handled through Odoo’s managed platform/database manager.

When an upgrade is offered, resist treating Upgrade Now as a shortcut around testing. Request and validate a test upgrade first.

Because Odoo Online does not support installing arbitrary Python custom modules, the custom-code migration model differs substantially from Odoo.sh and on-premise.

Odoo.sh

Odoo.sh is integrated with Odoo’s upgrade platform.

For a database with custom modules, a typical project separates custom-code work from production:

1. prepare the target-version custom code;
2. use a staging upgrade based on a recent production backup;
3. let Odoo.sh restore the upgraded backup and update custom modules;
4. inspect the upgrade log;
5. fix code/data migration issues;
6. push again and repeat until the staging upgrade succeeds.

Odoo’s current documentation describes an update-on-commit mode for this process: pushing commits to the upgrade branch can restore a pristine upgraded backup and update the custom modules again.

This is valuable because it makes the migration reproducible instead of gradually “fixing” one long-lived test database until nobody knows which manual changes were required.

On-premise

For on-premise databases, Odoo documents a command-line route for initiating a test upgrade:

python <(curl -s https://upgrade.odoo.com/upgrade) test \
  -d <your_db_name> \
  -t <target_version>

The exact environment requirements and target-version availability should be checked in the current official documentation before running it.

Odoo also provides its upgrade platform for submitting an upgrade request.

Do not forget the filestore

For on-premise-style upgrade handling, database data and attachment files must be treated together.

Odoo’s current upgrade documentation explains that the database copy submitted to the upgrade server is sent without the production filestore. The resulting upgraded filestore must be merged with the production filestore before the restored database represents a realistic test environment.

If the database opens but product images, documents or attachments are missing, you do not yet have a valid end-to-end test environment.

Step 4 — Upgrade the custom modules in parallel

If the database contains custom Python modules, database conversion and source-code migration are separate responsibilities.

Odoo explicitly states that custom-module source must be compatible with the target version before the complete upgrade can succeed.

A good custom-module sequence is:

1. Make the module installable on a clean Odoo 20 database

This exposes framework-level compatibility problems without customer data adding noise.

Review:

• __manifest__.py and dependencies;
• Python ORM code;
• models and fields;
• computed/inverse logic;
• XML views;
• actions and menus;
• ACLs and record rules;
• JavaScript/Owl code;
• asset bundles;
• controllers;
• reports;
• cron/server actions;
• tests.

2. Install/update it on the upgraded customer database

A module can install perfectly on a clean database and still fail against historical customer data.

That is where data migration becomes important.

If fields, models or XML IDs changed, use proper upgrade scripts and Odoo’s upgrade utilities where appropriate rather than manually patching production data.

3. Test what the module actually changes

Installation success is not business acceptance.

If a module modifies manufacturing, create and complete manufacturing scenarios.

If it modifies payroll, validate representative payslips and accounting output.

If it modifies POS, execute orders, payments, returns and closing.

If it modifies API behavior, run the external integration.

The test should follow the business effect of the customization.

Step 5 — Understand what the upgraded test database is not testing

This is one of the easiest parts of an Odoo upgrade to misunderstand.

Odoo neutralizes test databases so they do not accidentally behave like production.

Current documentation states that test upgrades disable or alter functions including:

• scheduled actions;
• outgoing mail servers;
• payment providers;
• delivery carriers;
• bank synchronization.

That is good for safety.

It also means a green UAT result does not automatically prove that every production integration will work after cutover.

Example

Suppose your sales flow is:

Website order
→ payment provider
→ sales order
→ stock reservation
→ carrier label
→ invoice
→ customer email
→ external accounting/BI sync

A neutralized test database may intentionally prevent several of those external steps from behaving exactly as production.

So the testing plan must distinguish:

A. Business logic validated inside the upgraded database

from:

B. External services that require sandbox credentials, controlled integration testing or immediate post-go-live verification.

That distinction belongs in the cutover plan.

Step 6 — Run end-to-end UAT, not a screen-by-screen tour

Opening menus and checking that forms render is not sufficient.

Odoo’s own upgrade documentation recommends testing business flows across applications.

Build scenarios around what employees actually do.

Sales-to-cash

Test:

1. create or convert a lead;
2. prepare a quotation;
3. confirm the sale;
4. reserve/deliver products;
5. generate the invoice;
6. register or test the payment flow;
7. validate resulting accounting/reporting;
8. test customer communications.

Purchase-to-pay

Test:

1. create a purchase order;
2. approve it where applicable;
3. receive products;
4. verify routes/lots/serials;
5. create the vendor bill;
6. validate taxes/accounts/analytic behavior;
7. verify payment/reconciliation workflow.

Inventory

Validate:

• routes;
• replenishment;
• warehouses/locations;
• packages;
• lots/serial numbers;
• internal transfers;
• returns;
• valuation;
• inter-company flows where applicable.

Manufacturing

Validate:

• BoMs;
• subassemblies;
• manufacturing orders;
• consumption;
• by-products;
• quality;
• work centers;
• stock results;
• costing/accounting consequences.

Accounting

Do more than open the Balance Sheet.

Test:

• representative invoices and bills;
• taxes;
• fiscal positions;
• credit notes;
• bank/reconciliation flows;
• analytic accounting;
• currencies;
• multi-company behavior;
• financial reports;
• localization-specific processes.

Website/eCommerce

Test:

• important pages;
• forms;
• shop search/catalog;
• cart;
• checkout;
• portal;
• translations;
• SEO-critical pages;
• payment and delivery in an appropriate test environment.

HR and operations

Test the workflows you actually use: attendance, time off, payroll, expenses, approvals, recruitment, planning, field service and documents.

Integrations and automation

Odoo specifically calls out external integrations, exports, automated actions and server actions as items that should not be forgotten.

Create a separate integration matrix with:

Step 7 — Compare data, not only behavior

A workflow can “work” while migrated data is wrong.

Select representative records and compare old production with the upgraded test database.

Examples:

• product category, price, cost, accounts, routes and vendors;
• customer/company fields;
• open sales and purchase orders;
• stock quantities and serials;
• receivables/payables;
• tax configuration;
• currencies;
• fiscal positions;
• employee/user access;
• analytic dimensions;
• saved filters and translations;
• attachments.

For finance-heavy implementations, define reconciliation totals before the cutover so the team knows exactly what numbers must match afterward.

Step 8 — Read the Upgrade Report

Odoo provides an Upgrade Report after an upgrade request.

Treat it as an input to testing, not as a certificate that testing is complete.

For customized databases, pay particular attention to disabled views and custom records affected by noupdate.

Odoo’s custom-upgrade guidance notes that views causing problems during upgrade may be disabled. If a required view was disabled, decide whether it should be migrated/re-enabled or removed because it is no longer useful.

The report helps identify known changes. Your business-specific testing still has to find the rest.

Step 9 — Rehearse before production

A production upgrade should not be the first time the team executes the complete sequence.

Before go-live, rehearse:

• final backup;
• code branch/tag;
• database submission/upgrade;
• custom-module update;
• upgrade scripts;
• filestore handling where applicable;
• configuration steps;
• smoke tests;
• integration checks;
• user access;
• stakeholder communication.

Record how long each stage takes.

Do not promise a production downtime window from a generic internet estimate. Measure your own rehearsal.

If the migration project takes weeks, request a fresh test upgrade before production. The production database and Odoo’s upgrade scripts can both evolve during a long project.

Step 10 — Plan the production freeze

Once the production upgrade starts, changes made to the old production database after the relevant copy/submission point will not magically appear in the upgraded database.

Create a clear freeze procedure.

It should specify:

• when users stop entering transactions;
• when integrations stop writing;
• when eCommerce/order intake is paused or redirected if necessary;
• who confirms the freeze;
• when the final backup is taken;
• who triggers the upgrade;
• who deploys target-version code;
• who performs technical smoke tests;
• who performs business validation;
• who makes the go/no-go decision.

Odoo’s documentation warns that the production database is unavailable during the upgrade process. For Odoo Online, it also states that after a successful production upgrade you cannot simply revert the database to the previous version.

On Odoo.sh, the platform has its own rollback behavior if the upgrade operation fails. That is not the same thing as treating a successfully completed major-version upgrade as casually reversible.

Design the cutover accordingly.

Step 11 — Run a strict post-upgrade go-live gate

Immediately after production comes up, validate the smallest set of checks that can detect a critical failure quickly.

Technical smoke test

• database starts cleanly;
• target Odoo version is correct;
• expected modules are installed;
• custom modules load;
• critical views open;
• scheduled actions are in the expected state;
• users can authenticate;
• permissions behave correctly;
• website/portal responds;
• background workers/jobs are healthy.

Business smoke test

Use representative high-value workflows:

• create/confirm a sale;
• reserve/complete stock;
• create an invoice;
• validate a purchase/receipt;
• verify a critical report;
• run a manufacturing scenario if relevant;
• verify a payroll/HR workflow if relevant.

External-system smoke test

Re-enable or verify controlled production connections in a deliberate order:

• outgoing email;
• payment provider;
• carrier;
• bank/EDI where applicable;
• mobile/portal integrations;
• middleware/webhooks;
• BI/data sync.

Do not turn everything on and wait for users to discover what failed.

What Odoo’s standard upgrade service does — and does not — cover

This distinction is important when budgeting an Odoo 20 upgrade.

Odoo’s current Enterprise upgrade documentation says the upgrade service covers the technical conversion of standard applications and data, and includes certain Studio/customization scenarios depending on the applicable subscription/maintenance coverage.

It also lists items outside the standard upgrade SLA, including:

• cleaning pre-existing data/configuration;
• upgrading additional in-house or third-party modules that are not covered by a maintenance contract;
• training users on new-version features and workflows.

For many customized businesses, those “outside” items are where much of the actual project effort lives.

That is why “Odoo upgrades the database” and “our company is ready to operate safely on Odoo 20” are not equivalent statements.

Common Odoo 20 upgrade mistakes

1. Upgrading production first

A production database is not a test environment. Request and validate a test upgrade.

2. Porting every customization

Challenge custom code first. Native Odoo 20 functionality may make some modules unnecessary.

3. Testing screens instead of processes

A form opening successfully does not prove the order-to-cash flow works.

4. Ignoring neutralization

Test databases intentionally disable external behavior. Plan separate validation for production integrations.

5. Testing only custom modules

Standard workflows change too. Users need to test the upgraded business process, not just developer code.

6. Forgetting historical data

A module that installs on an empty Odoo 20 database can still fail when old records are migrated.

7. Ignoring the filestore

For applicable on-premise upgrade flows, database and filestore handling must be coordinated.

8. Skipping the rehearsal

Without a rehearsal, downtime estimates and cutover steps are guesses.

9. Treating the upgrade report as complete UAT

It is useful evidence, not a replacement for business testing.

10. Mixing too many projects into one cutover

A major-version upgrade, hosting migration, edition change, data cleanup and complete process redesign are separate risks. Combine them only when there is a deliberate reason and a testable plan.

How long does an Odoo 20 upgrade take?

There is no responsible universal answer.

The effort depends on:

• source-version gap;
• number and complexity of custom modules;
• third-party apps;
• data volume;
• integrations;
• accounting/localization complexity;
• number of companies;
• website/eCommerce;
• manufacturing/inventory complexity;
• defects already present in production;
• availability of business users for UAT.

The database conversion itself may be only one part of the elapsed project.

For a heavily customized system, custom-code migration and business validation can dominate the schedule.

The best estimate comes after the first test upgrade and customization inventory—not before.

Odoo 20 upgrade checklist

Discovery

• Confirm source version, edition and hosting.
• Confirm Odoo 20 is currently available as an upgrade target for the exact database path.
• Inventory standard, Studio, third-party and custom modules.
• Inventory integrations and automations.
• Define business-critical workflows.
• Assign technical and business owners.

Development

• Freeze non-essential old-version development.
• Challenge/remove obsolete customizations.
• Prepare target-version code branch.
• Make custom modules installable on clean Odoo 20.
• Prepare required upgrade scripts.
• Validate modules against upgraded customer data.

Testing

• Review the Upgrade Report.
• Check disabled/custom views.
• Run role-based UAT.
• Test cross-app workflows.
• Compare representative migrated records.
• Reconcile financial/stock data.
• Test reports, exports, translations and templates.
• Test integrations using safe environments.
• Record known neutralization limitations.

Cutover

• Run a fresh rehearsal.
• Measure the actual sequence/downtime.
• Communicate freeze window.
• Stop writes/integrations at the agreed time.
• Take/verify final backup where applicable.
• Trigger production upgrade.
• Deploy target-version custom code.
• Complete filestore handling where applicable.
• Run technical/business/integration smoke tests.
• Obtain business go-live approval.

Frequently asked questions

Can I upgrade directly to Odoo 20?

Potentially, but do not infer this from Odoo 20 being released. Check the current Odoo upgrade tooling for your exact source version, edition and hosting setup before planning the project.

Do I need to upgrade custom modules separately?

Yes, if your deployment contains custom Python modules. Odoo’s database upgrade and your custom source-code migration are related but distinct parts of the project. Odoo states that custom-module source must be compatible with the target version for the complete upgrade to succeed.

Can I test an Odoo upgrade without affecting production?

Yes. Odoo’s process is built around upgraded test databases. Test databases are neutralized to reduce the risk of sending production emails, payments or other external actions.

Can I request more than one test upgrade?

Yes. Odoo’s documentation says multiple test databases can be requested, and fresh test upgrades are particularly useful when the migration project lasts long enough for production data or upgrade scripts to change.

Is an Odoo upgrade the same as changing hosting?

No. Odoo explicitly treats changing hosting type as separate from the database upgrade.

Is an Odoo upgrade the same as Community-to-Enterprise migration?

No. Switching editions is not part of the standard database-upgrade definition.

Will Odoo upgrade our third-party custom modules?

Do not assume so. Odoo’s standard upgrade SLA does not include additional in-house or third-party modules unless they fall under applicable customization maintenance coverage. Confirm responsibility before starting the project.

Can we roll back after upgrading production?

Treat a successful major-version production upgrade as irreversible. Odoo’s current documentation explicitly describes the upgrade operation as irreversible and, for Odoo Online production upgrades, says it is impossible to revert to the previous version after completion. Hosting platforms may have failure-recovery mechanisms during the operation, but that is different from casually downgrading a successfully upgraded production database.

Final takeaway

A safe Odoo 20 upgrade has three migrations happening together:

the database, the custom code, and the business operation.

Odoo’s upgrade platform can convert the standard database. Developers can make custom code compatible. But the business still has to prove that sales, accounting, inventory, manufacturing, HR, websites, integrations and daily user workflows work correctly with real upgraded data.

The best upgrade projects therefore follow one rule:

Never make production the place where you discover whether your migration plan works.

Test it. Fix it. Repeat it. Rehearse it. Then cut over.

Planning an Odoo 20 project? Octivex Tech helps businesses with Odoo upgrades, custom module migration, integrations and AI-enabled workflows. Explore our Odoo services or contact our engineering team to discuss your environment.