Odoo Migration Guide: Upgrade & Migrate Data

Odoo Migration Guide: How to Upgrade & Move Data with Zero Business Friction

Migrating an ERP system is one of the most critical technical operations a business will undertake. Whether you are upgrading from Odoo 15/16 to Odoo 18 or 19, moving from Odoo.sh to self-hosted infrastructure, or transitioning off legacy software like sevDesk, SAP, or QuickBooks, a botched migration risks lost financial history, broken inventory tallies, and unneeded business downtime.

This guide provides a practical, real-world framework for executing an Odoo migration smoothly—protecting your data integrity while ensuring your operational workflows transition without missing a beat.

The 3 Types of Odoo Migrations

Before touching a single script or database table, you must clearly identify which type of migration your organization requires. Each path carries distinct technical complexities and downtime profiles.

Types of Odoo Migrations

1. Version Upgrades (Major Releases)

Upgrading your current instance to a newer Odoo release (e.g., moving from version 16 or 17 to version 18 or 19).

• Technical Requirements: Database schema transformations, module API updates, PostgreSQL dependency checks, and QWeb report refactoring.
• Primary Risk: Custom code or third-party apps breaking due to deprecated framework methods in the new version.

2. Infrastructure & Hosting Migrations

Moving an existing Odoo instance across servers without changing the Odoo version (e.g., moving off Odoo.sh to dedicated cloud hosting on AWS/DigitalOcean, or vice versa).

• Technical Requirements: Transferring PostgreSQL database dumps, syncing the attachment filestore (/var/lib/odoo/.local/share/Odoo/filestore), and aligning system dependencies (Python, Wkhtmltopdf).
• Primary Risk: Filestore permission mismatches resulting in broken invoice PDFs or missing product photos.

3. Legacy System Data Migrations

Leaving non-Odoo platforms (such as sevDesk, Excel spreadsheets, QuickBooks, or custom SQL databases) to launch a fresh Odoo environment.

• Technical Requirements: Extracting raw legacy data, cleansing record structures, mapping relational IDs, and importing clean CSV/XLSX/JSON sets.
• Primary Risk: Duplicate customer contacts, orphaned transactional records, or misaligned starting financial balances.

6-Stage Execution Plan for a Risk-Free Migration

Executing a successful enterprise migration requires an isolated test environment and zero guesswork.

┌──────────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│  1. AUDIT &  │──►│ 2. STAGING   │──►│  3. CODE &   │──►│ 4. TEST &    │
│   CLEANSE    │   │ SETUP (TEST) │   │ DATA SCRIPT  │   │  VALIDATE    │
└──────────────┘   └──────────────┘   └──────────────┘   └──────────────┘
                                                                │
                                                                ▼
                                                       ┌────────────────┐
                                                       │ 5. CUTOVER &   │
                                                       │    GO-LIVE     │
                                                       └────────────────┘

Stage 1: System Audit & Data Hygiene

• Audit Custom Modules: Compile a complete inventory of standard Odoo apps, third-party App Store modules, and custom-coded apps. Determine whether custom features are still needed or if standard features in newer Odoo releases replace them.

• Cleanse Historical Data: Archive inactive records, resolve duplicate contacts, and balance unposted accounting entries.

• Review Infrastructure: Verify that the target server environment supports the Python version, PostgreSQL release, and memory limits required by your target Odoo version.

Stage 2: Staging Environment Isolation

Never attempt an upgrade or data migration directly on a live production instance.

• Create a complete clone of your live production database and filestore.

• Provision an isolated staging environment (staging.yourcompany.com).

• Disable all live integrations (payment gateways, courier APIs, automated email triggers) inside the staging environment to prevent sending test data to real clients or carriers.

Stage 3: Code Adaptation & Schema Migration

• Update custom module manifests and codebase to align with new Odoo ORM APIs.

• Convert deprecated QWeb/XML views, field definitions, and controllers.

• Execute database schema migration using official upgrade scripts (Odoo Enterprise Upgrade API) or community tools like OpenUpgrade for Community editions.

Stage 4: User Acceptance Testing (UAT)

Engage your key business stakeholders to validate critical business processes end-to-end within the staging environment:

• Finance: Validate trial balance matches, tax code mapping, and open invoice balances.

• Logistics & Sales: Confirm stock availability levels, product variant definitions, and incoming/outgoing delivery workflows.

• Customer Data: Verify contact relational records (parent-child company relationships, delivery addresses).

Stage 5: Final Production Cutover

• Freeze live production access (enable maintenance mode to prevent user updates).

• Take a final, clean database dump and copy the full filestore.

• Run the tested migration scripts on the final production dataset.

• Update DNS records, SSL certificates, and reactivate external integrations.

Stage 6: Post-Go-Live Monitoring

Monitor system performance, server memory, CPU utilization, and PostgreSQL query logs for 48–72 hours following the cutover. Maintain the legacy backup instance in read-only mode for reference.

Key Technical Comparisons & Migration Tooling

Common Migration Pitfalls (and How to Avoid Them)

1. Hardcoding Data IDs in Custom Code

• The Risk: Standard Odoo internal IDs (xml_id or database IDs) often change across major software releases or fresh imports.

• The Solution: Use external XML IDs (ir.model.data) or key lookup attributes (such as internal references or tax numbers) instead of raw numerical database IDs when scripting data imports.

2. Disregarding the Filestore Copy

• The Risk: Only exporting the PostgreSQL .sql dump leaves behind all visual attachments, invoice PDFs, image variants, and document attachments stored in the physical directory.

• The Solution: Always pair your database dump with a synchronized copy of the exact filestore folder:

rsync -avz /var/lib/odoo/.local/share/Odoo/filestore/ target_server:/var/lib/odoo/.local/share/Odoo/filestore/

3. Untested Third-Party App Upgrades

• The Risk: Installing standard vendor apps in a new Odoo version before verifying their backend database structure can corrupt historical data lines.

• The Solution: Audit all third-party app vendors 30–60 days before migration to secure compatible module versions and verify upgrade migration paths.

Pre-Migration Readiness Checklist

Before you schedule a single migration task, confirm these seven items. Skipping any one of them is the most common reason a "1-week migration" turns into a 4-week fire drill.

• Full module inventory exists — every Community app, OCA app, App Store app, and custom module is listed with its current version and whether it's still actually used.
• A named business owner signs off on UAT — not "someone from finance will look at it eventually." One person per department (Sales, Inventory, Accounting) who is accountable for saying "this matches production."
• Staging hardware matches production — same PostgreSQL version, same Python version, same worker count if feasible. Migrations that pass on an underpowered staging box can still time out or deadlock on the real dataset.
• Third-party API credentials for staging are separate from production — payment gateways, shipping carriers, and marketing tools all need sandbox/test credentials so staging testing doesn't touch real customers or real money.
• A rollback point is defined and tested, not just assumed (see the Rollback Plan section below).
• A maintenance-mode communication is drafted for customers/staff before cutover day, not written in a panic during the freeze window.
• Someone owns DNS/SSL/webhook re-pointing if the migration also changes hosting — this step gets forgotten more often than the database migration itself.

How Long Does an Odoo Migration Actually Take?

"It depends" is true but not useful. Here's what actually drives the timeline, based on the migration paths above:

A single-company instance with no custom modules and under 10,000 records can realistically move in 3–5 days including UAT. A multi-company instance with 15 custom modules and four live integrations is a 4–8 week project, not a weekend job — and any quote that promises otherwise is quoting the database copy, not the actual migration.

Running OpenUpgrade for Community Edition

If you're on Odoo Community and don't have access to the official Enterprise Upgrade Platform, OpenUpgrade (maintained by the OCA) is the standard community path for version-to-version schema migration. A simplified single-step run looks like this:

# 1. Clone OpenUpgrade at the branch matching your TARGET version
git clone -b 18.0 https://github.com/OCA/OpenUpgrade.git

# 2. Create a fresh virtualenv and install OpenUpgrade's requirements
python3 -m venv openupgrade-venv
source openupgrade-venv/bin/activate
pip install -r OpenUpgrade/requirements.txt

# 3. Restore a COPY of your production database under a new name —
#    never point this at the live database
createdb odoo_migration_test
pg_restore -d odoo_migration_test production_backup.dump

# 4. Run the upgrade against the copy, module by module or with -u all
./OpenUpgrade/odoo-bin -d odoo_migration_test \
  --addons-path=OpenUpgrade/addons,custom-addons \
  -u all --stop-after-init

A few things that matter more than the commands themselves:

• Multi-step jumps go version by version internally. Going from Odoo 15 to Odoo 18 means OpenUpgrade effectively steps through 15→16→17→18 — budget testing time for each intermediate state, not just the final one.
• --stop-after-init is not optional for the first pass. You want the migration to run, log its errors, and stop — not silently continue into a half-upgraded state you then have to diagnose live.
• Custom modules need their own OpenUpgrade migration scripts (migrations/<version>/pre-migration.py / post-migration.py) if they touch fields or models that changed shape between versions. This is the step most self-migrated projects skip, and it's usually where the data corruption shows up two weeks later, not on migration day.

Rollback Plan: What Happens If Cutover Goes Wrong

Every migration plan needs a written answer to "what do we do if this fails at 2am on cutover night" — decided in advance, not improvised under pressure.

1. Keep the pre-migration production dump and filestore untouched and read-only until the new environment has run cleanly in production for at least one full business cycle (typically 1–2 weeks).
2. Define your rollback trigger in advance — e.g., "if trial balance doesn't match within €50, or if any P1 workflow (invoicing, stock movement) is broken 4 hours after go-live, we roll back." Deciding this during an incident, under pressure, produces worse decisions than deciding it calmly beforehand.
3. DNS/routing rollback should be a single reversible step — keep the old environment reachable at a fallback URL (not deleted, not repurposed) so cutover-back is a routing change, not a restore-from-backup exercise.
4. Test the rollback once, on staging, before go-live. A rollback procedure nobody has actually executed is a hope, not a plan.

Post-Migration Validation Checklist

Once you're live on the new version or new server, verify these before declaring the migration complete — not just "it loaded without an error":

• Trial balance on the new system matches the final pre-cutover trial balance exactly.
• A sample of the 20 most recent invoices/orders across each company render correctly as PDFs (this is where filestore issues show up first).
• Stock quantities for a sample of high-velocity products match physical/expected counts.
• All scheduled actions (cron jobs) that existed pre-migration are still active — these are silently disabled on some upgrade paths and nobody notices until a nightly sync stops running.
• Every third-party integration has fired at least one successful transaction in the new environment (a test order through the actual payment gateway, not just a connectivity check).
• User access rights and record rules match the pre-migration configuration — a common and dangerous miss is a security group losing a rule during the schema upgrade.
• Automated emails (order confirmations, invoices) are sending from the correct domain and not landing in spam due to a changed sending IP.

Frequently Asked Questions

Can I migrate Odoo myself without a consultant? If you're on a single-company instance with no custom modules and a small dataset, yes — Stage 1 through Stage 6 above is a reasonable DIY roadmap. Once custom modules, multiple integrations, or multi-company accounting are involved, the failure modes (silently broken automations, mismatched trial balances, corrupted relational IDs) are hard to catch without having seen them before.

Does upgrading lose my customizations? Not automatically, but they don't upgrade themselves either. Every custom module needs to be reviewed against the target version's ORM and view API before the upgrade — deprecated methods and changed field behaviors are the most common source of a "successful" migration that breaks a specific workflow days later.

How much downtime does an Odoo migration require? A server/hosting migration (Path 2 above) can often be under an hour with a well-rehearsed pg_dump/rsync/DNS cutover. A version upgrade with custom modules typically needs a scheduled maintenance window of 2–6 hours for the final cutover, even though the staging work behind it takes days or weeks.

What's the difference between Odoo's official Upgrade Platform and OpenUpgrade? The official Odoo Upgrade Platform (Enterprise) is Odoo S.A.'s own automated schema-migration service — faster and officially supported, but it doesn't touch third-party or custom module compatibility for you. OpenUpgrade is the OCA-maintained open-source path used mainly by Community edition instances, and it requires more manual verification since there's no vendor support behind it.

Why Professional Migration Planning Matters

A successful Odoo migration relies on deep technical knowledge of Odoo's ORM, database architecture, and practical operational logic. Partnering with experienced Odoo consultants ensures your business critical data remains safe, accurate, and ready for future growth.

If this raised more questions than it answered, that's normal — every Odoo setup has its own quirks. I help with Odoo migration and Odoo implementation for businesses in Germany and internationally. Get in touch if you want a second opinion before you commit to an approach.