Odoo Migration Guide — Version Upgrades, Data Migration & Platform Moves

1Types of Odoo Migration

"Odoo migration" means different things depending on your situation. Before diving into specifics, identify which type of migration you need. Most projects involve one or two of these simultaneously.

The rest of this guide covers each type in detail with specific commands, timelines, and gotchas. If you are doing a version upgrade and a platform move at the same time, handle them separately: upgrade first on your current platform, verify everything works, then move to the new platform.

2Odoo Version Migration (17 → 18 → 19)

Odoo releases a new major version every year. Each release brings new features, UI improvements, and API changes. As of early 2026, the active versions are Odoo 18 LTS (the current long-term support release) and Odoo 19 (the latest release). Versions 16.0 and earlier are end-of-life for official support.

Version Lifecycle

What Changes Between Versions

Every major version update touches three areas: the database schema (table structures, new fields, renamed columns), the Python API (method signatures, deprecated functions, new decorators), and the web framework (OWL components, JavaScript assets, template syntax). Standard Odoo modules handle these changes through migration scripts. Custom modules need manual updates.

Pre-Migration Checklist

The Upgrade Process

There are three main approaches to upgrading an Odoo database:

# Step 1: Create database dump
pg_dump -Fc -f odoo_production.dump odoo_production
# Step 2: Upload to upgrade.odoo.com (via web UI or API)
# API example:
curl -F "db=@odoo_production.dump" \
     -F "contract=YOUR_CONTRACT_NUMBER" \
     -F "target=18.0" \
     -F "aim=production" \
     https://upgrade.odoo.com/database/v1/upload
# Step 3: Download the upgraded database when ready
# Step 4: Restore locally for testing
pg_restore -d odoo_staging --no-owner odoo_upgraded.dump

# Clone OpenUpgrade for target version
git clone https://github.com/OCA/OpenUpgrade.git --branch 18.0 --depth 1
cd OpenUpgrade
# Install dependencies
pip install -r requirements.txt
# Run the migration (point to your 17.0 database)
python odoo-bin -d odoo_production \
  --update=all \
  --stop-after-init \
  --load=base,web,openupgrade_framework \
  --addons-path=addons,odoo/addons

Post-Migration Testing

After upgrading the database, run these verification steps on your staging environment before touching production:

• Start Odoo with --update=all --stop-after-init to verify all modules load without errors
• Log in and check each installed module's settings page
• Run through critical business workflows: create a sales order, confirm it, generate an invoice, register payment
• Check that reports (PDF invoices, delivery slips) render correctly
• Verify scheduled actions (cron jobs) are configured and running
• Spot-check data: compare record counts, random invoice totals, and inventory quantities against the source
• Test user permissions. Different user roles should still have correct access

3Migrate from Odoo.sh

Odoo.sh is Odoo's managed platform. It works well for getting started, but many companies eventually outgrow it due to pricing ($50+/user/month adds up fast), limited server configuration options, and dependency on a single vendor for infrastructure. Moving to self-hosted or a platform like OEC.sh gives you full control over your stack, your costs, and your data.

For a detailed comparison, see OEC.sh vs Odoo.sh. For a step-by-step walkthrough with screenshots, check the dedicated Migrate from Odoo.sh page.

Step-by-Step: Odoo.sh to Self-Hosted

# From Odoo.sh shell (SSH)
pg_dump -Fc -f /tmp/production_backup.dump $PGDATABASE
# Download via SCP (from your local machine)
scp your-project@odoo.sh:/tmp/production_backup.dump ./

# From Odoo.sh shell
tar -czf /tmp/filestore_backup.tar.gz /home/odoo/data/filestore/
# Download from your local machine
scp your-project@odoo.sh:/tmp/filestore_backup.tar.gz ./

# On your new server: stop Odoo
sudo systemctl stop odoo
# Drop the empty database and restore from backup
sudo -u postgres dropdb odoo_production
sudo -u postgres pg_restore -d odoo_production --no-owner production_backup.dump
# Extract filestore
sudo tar -xzf filestore_backup.tar.gz -C /opt/odoo/.local/share/Odoo/filestore/
sudo chown -R odoo:odoo /opt/odoo/.local/share/Odoo/filestore/
# Start Odoo
sudo systemctl start odoo

Downtime Expectations

For a clean cut-over, plan for 1-4 hours of downtime depending on your database size. A 5 GB database takes roughly 15-30 minutes to dump and 15-30 minutes to restore. The rest is DNS propagation (use a low TTL ahead of time) and verification. If you need near-zero downtime, set up the new server in advance, do a preliminary sync, then do a final incremental sync during a short maintenance window.

4Data Migration from Other ERPs

Switching from SAP, QuickBooks, ERPNext, Sage, or another system to Odoo is a different challenge than version upgrades. There is no automatic migration tool because every source system stores data differently. The general approach is: export data from the old system, transform it into Odoo's expected format, then import it.

General Migration Approach

# Example: Import contacts via XML-RPC
import xmlrpc.client
url = "https://your-odoo.example.com"
db = "odoo_production"
uid = 2  # admin user ID
password = "your-api-key"
models = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/object")
# Create a partner
partner_id = models.execute_kw(db, uid, password,
    'res.partner', 'create', [{
        'name': 'Acme Corp',
        'email': 'info@acme.com',
        'phone': '+1-555-0100',
        'is_company': True,
        'customer_rank': 1,
    }])
print(f"Created partner ID: {partner_id}")

Source-Specific Tips

5Database Migration

Database migration covers two scenarios: moving a PostgreSQL database between servers (same version), and upgrading PostgreSQL itself (e.g., 14 to 16). Both are straightforward with the right approach. For backup fundamentals, see the Odoo Backup and Recovery Guide.

Moving PostgreSQL Between Servers

The standard pg_dump/pg_restore workflow works for any server-to-server move, whether you are going from AWS to Hetzner, switching VPS providers, or moving to a dedicated database server.

# On the source server: create a compressed dump
pg_dump -Fc -Z 5 -f /tmp/odoo_dump.backup odoo_production
# Transfer to destination server
rsync -avz --progress /tmp/odoo_dump.backup user@new-server:/tmp/
# On the destination server: create database and restore
sudo -u postgres createdb -O odoo odoo_production
sudo -u postgres pg_restore -d odoo_production --no-owner --role=odoo /tmp/odoo_dump.backup
# Don't forget the filestore
rsync -avz /opt/odoo/.local/share/Odoo/filestore/ user@new-server:/opt/odoo/.local/share/Odoo/filestore/

Upgrading PostgreSQL (14 → 15 → 16)

When upgrading PostgreSQL on the same server, you have two options: pg_upgrade (in-place, faster) or dump-and-restore (safer, works across machines). For Odoo databases, dump-and-restore is recommended because it reindexes everything and avoids compatibility quirks.

# Step 1: Install new PostgreSQL version alongside the old one
sudo apt install postgresql-16
# Step 2: Dump from old version
sudo -u postgres /usr/lib/postgresql/14/bin/pg_dump -Fc odoo_production > /tmp/odoo_pg14.dump
# Step 3: Stop old PostgreSQL, start new one
sudo systemctl stop postgresql@14-main
sudo systemctl start postgresql@16-main
# Step 4: Create role and database on new version
sudo -u postgres createuser -s odoo 2>/dev/null || true
sudo -u postgres createdb -O odoo odoo_production
# Step 5: Restore into new version
sudo -u postgres pg_restore -d odoo_production --no-owner /tmp/odoo_pg14.dump
# Step 6: Update Odoo config if the port changed
# Check /etc/postgresql/16/main/postgresql.conf for the port
# Update db_port in /etc/odoo/odoo.conf if needed
# Step 7: Restart Odoo
sudo systemctl restart odoo

Cross-Cloud Migration

Moving between cloud providers (AWS RDS to self-managed, DigitalOcean to Hetzner, etc.) follows the same dump-and-restore pattern. The main considerations are network transfer speed and security:

# For large databases, compress and encrypt during transfer
pg_dump -Fc -Z 9 odoo_production |   gpg --symmetric --cipher-algo AES256 |   ssh user@new-server "cat > /tmp/odoo_encrypted.dump.gpg"
# On the new server: decrypt and restore
gpg --decrypt /tmp/odoo_encrypted.dump.gpg |   pg_restore -d odoo_production --no-owner

6Module Migration

When you upgrade Odoo versions, every custom module needs to be updated for the new release. Standard Odoo modules and OCA modules are handled by the upgrade service and the OCA maintainers respectively. Your private/custom modules are your responsibility. This is often the most labor-intensive part of a version upgrade.

Common API Changes Between Versions

Each Odoo version introduces breaking changes. These are the typical areas that require module updates:

OCA Module Compatibility

OCA modules are maintained by volunteers and typically get ported to new versions within 3-6 months of release. Check the branch list on the OCA GitHub repository to see if your required modules have been ported. The OCA Modules Guide covers how to find and install OCA modules for any version.

# Check if an OCA module has been ported to 18.0
git ls-remote --heads https://github.com/OCA/account-financial-tools.git | grep 18.0
# If the branch exists, clone it
git clone https://github.com/OCA/account-financial-tools.git --branch 18.0 --depth 1

Testing Workflow: Staging → Test → Production

Never test module migrations on production. Use this workflow:

1. Development: Update the module code on your local machine or dev server. Fix import errors, deprecated API calls, and template issues.
2. Staging: Deploy the updated module to a staging environment with a copy of production data. Run -u module_name --stop-after-init to verify the upgrade script runs cleanly.
3. User Acceptance Testing: Have actual users test their workflows on staging. They will catch issues that automated tests miss, like button placement, form flow, and report formatting.
4. Production: Schedule a maintenance window, take a backup, deploy the updated modules, and run the upgrade.

7Migration with OEC.sh

OEC.sh has several features that simplify migration, whether you are upgrading versions, switching platforms, or doing both at the same time.

See OEC.sh Features for the full list of platform capabilities, or check Pricing to find a plan that fits your migration needs.

8Migration Checklist

Use these checklists to track your migration progress. Print them out or copy into your project management tool.

9Frequently Asked Questions