Odoo Migration Guide: Moving from v16/v17/v18 to v19/v20

Odoo releases one major version per year. Migration is inevitable — the question is whether it will take 3 weeks or 6 months. The difference comes down almost entirely to the quality of your custom code base and how well you prepare. Here's the complete technical guide we apply to our migration projects.

Phase 1: Audit Your Current Database (Before Anything Else)

Before talking migration, audit what you have. The 4 issues that multiply migration cost:

• ✓Direct edits to Odoo core files → must be refactored as _inherit modules BEFORE migration
• ✓Integer ID references in XML/Python data → must be converted to XML IDs (module.record_id)
• ✓Dependencies on undocumented methods (prefixed with _ or not in official docs) → identify and replace
• ✓XML-RPC in third-party integrations → migrate to JSON-2 API (deprecated in v20, removed in v22)

Phase 2: Dedicated Staging Environment

The absolute rule: never test a migration in production. Create an identical staging environment:

• ✓Production database dump restored to staging (real data, not test data)
• ✓All custom modules at the same version as production
• ✓Same PostgreSQL version (Odoo 20 requires PostgreSQL 16 minimum)
• ✓Same Python version (Odoo 20 requires Python 3.12 minimum)
• ✓Isolated environment variables (no connections to production systems)

Phase 3: Custom Module Migration

For each custom module, the procedure:

• ✓Check compatibility in manifest.py: update 'version' and 'odoo_version_info'
• ✓For Odoo 20: migrate Owl 2 frontend components → Owl 3 (hooks and lifecycle change)
• ✓Test every XML view against the new framework — namespaces may change
• ✓Check model inheritances: if Odoo renames or removes an inherited field, the module breaks
• ✓Run migration scripts in the migrations/[version]/pre-migrate.py and post-migrate.py folders
• ✓For data: write Python scripts that transform records from the old model to the new one

Phase 4: API Migration (XML-RPC → JSON-2)

If any external systems (ERP, e-commerce, BI, import scripts) use Odoo's XML-RPC API, migration is urgent:

• ✓XML-RPC: /xmlrpc/2/common and /xmlrpc/2/object → legacy mode since v20, removed in v22
• ✓JSON-2: new standardized endpoint with API key authentication and scopes
• ✓Audit: grep -r 'xmlrpc' across all integration source code
• ✓Migrate integration by integration: test on staging before switching production
• ✓JSON-2 API keys: create in Odoo → Settings → API Keys, configure scopes (read/write per module)

Phase 5: Realistic Acceptance Testing

Don't test with fake data ('Test Customer 1'). Build scenarios with your real customers, real products, real workflows. Test specifically:

• ✓Full sales cycle: quote → order → delivery → invoice → payment
• ✓Accounting reconciliation with real bank statements
• ✓All custom PDF reports
• ✓Critical integrations (payments, logistics, e-commerce)
• ✓Access rights: test each user profile
• ✓Automations: manually trigger each Automated Action

Phase 6: Go-Live and Stabilization

• ✓User training: 1-2 weeks before go-live, not on the day
• ✓Train by role: sales reps learn Sales, accountants learn Accounting
• ✓Keep the old system running in parallel for 1-2 months (compare outputs)
• ✓First stable Odoo patch: wait 4-6 weeks post-GA before migrating production
• ✓Intensive support for the first 2 weeks post go-live
• ✓For Odoo 20 specifically: GA mid-October 2026, first stable patch November 2026

A well-prepared migration takes 2-4 weeks. A migration on a codebase overloaded with undocumented custom code can take 6 months. Investing in code quality now is always cheaper than paying for it at the next migration.