Odoo 17 to 19 Migration: 2026 Step-by-Step Guide (Custom Code)

Upgrading to Odoo 19 Enterprise delivers significant improvements in performance, user experience, and AI-assisted features. But migration is one of the highest-risk operations in an ERP lifecycle — data loss, broken custom modules, and extended downtime are all real risks that require careful planning and execution.

This guide provides a practical, step-by-step migration methodology for organizations moving from Odoo 17 or Odoo 18 to Odoo 19 Enterprise. It covers everything from initial assessment and data mapping to custom module updates, testing procedures, and the go-live cutover plan.

Key Takeaways

• Odoo 19 migration requires upgrading one major version at a time (17→18→19 or 17→19 directly with OpenUpgrade)
• Custom module compatibility must be verified against Odoo 19's API changes
• Data migration runs through Odoo's official upgrade platform or OpenUpgrade
• A parallel testing environment is mandatory before production cutover
• Plan for 3-8 weeks total migration timeline depending on complexity
• Financial periods must be closed before cutover to avoid reconciliation issues
• All third-party integrations need re-verification after migration
• Rollback plan must be documented and tested before go-live

---

Migration Planning: Assessment Phase

Before writing a single migration script, invest time in thorough assessment. Migrations fail most often due to inadequate planning, not technical complexity.

Step 1: Inventory your current environment

Document every component of your current Odoo installation:

Current Environment Inventory:
- Odoo version: 17.0.x or 18.0.x
- Edition: Community or Enterprise
- Database size: X GB, Y records in sale.order, Z in account.move
- Installed modules: [list all modules]
- Custom modules: [list with developer contact]
- Third-party connectors: [Amazon, Shopify, etc.]
- Active integrations: [API, webhooks, cron jobs]
- Customized reports: [list]
- Custom fields (Studio or code): [list]
- Server specs: RAM, CPU, disk
- PostgreSQL version: (minimum 15 required for Odoo 19)

Step 2: Classify custom modules

For each custom module, determine:

Step 3: Identify Odoo 19 breaking changes

Key changes between Odoo 17/18 and Odoo 19 that affect custom modules:

• OWL 3.x: Frontend components must be migrated from OWL 2.x patterns
• Python 3.12: Some Python 3.10/3.11 syntax may need adjustment
• PostgreSQL 15+: Required minimum version; some query patterns change
• API deprecations: Several _legacy methods removed; check for _multi → _create_multi
• Report engine: Some QWeb report variables renamed
• Account move refactoring: account.move line structure changes affect accounting customizations

---

Choosing Your Migration Path

Path 1: Odoo Official Upgrade Service

Odoo SA provides an automated upgrade service at upgrade.odoo.com. You submit your database, they run migration scripts developed and maintained by Odoo SA, and you receive an upgraded database.

Pros:

• Official support and testing by Odoo SA
• Handles database schema changes automatically
• Suitable for standard Odoo with minimal customizations

Cons:

• Does not handle custom modules
• Requires submitting production data to Odoo's servers
• Limited control over the migration process
• Custom module migration is your responsibility

Path 2: OpenUpgrade (Community Tool)

OpenUpgrade is an open-source project that provides migration scripts for Community and Enterprise.

# Clone OpenUpgrade for Odoo 19
git clone https://github.com/OCA/OpenUpgrade.git -b 19.0

# Install upgrade dependencies
pip install openupgradelib

# Run migration
python odoo-bin --config=upgrade.conf \
    --update=all \
    --load=base,web,openupgrade_framework

Path 3: Fresh Install with Data Import

For heavily customized instances or very old versions:

1. Set up a fresh Odoo 19 Enterprise instance
2. Reconfigure all modules and settings
3. Export critical data from the old system
4. Import via Odoo's import tool or custom migration scripts
5. Manually re-enter opening balances for accounting

This path is slower but provides the cleanest starting point.

Recommended for most Odoo 17/18 → 19 migrations: Path 1 or 2 combined with a parallel custom module redevelopment effort.

---

Pre-Migration Preparation (Weeks 1-2)

Database preparation:

-- Run on source database before export
-- Identify orphaned records
SELECT id, name FROM res_partner WHERE active = FALSE AND id NOT IN (
    SELECT partner_id FROM sale_order
    UNION SELECT partner_id FROM account_move
    UNION SELECT partner_id FROM stock_picking
);

-- Archive old draft records (reduces migration time)
UPDATE sale_order SET active = FALSE
WHERE state = 'draft' AND date_order < NOW() - INTERVAL '2 years';

-- Verify accounting reconciliation
SELECT COUNT(*) FROM account_move_line
WHERE reconciled = FALSE AND debit != credit;

Close financial periods:

Before migration:

1. Lock all periods before the current month in Odoo Accounting
2. Run the aged receivables and payables reports and reconcile differences
3. Reconcile all bank statements through the migration date
4. Post all draft invoices that should be included in historical data

Backup everything:

# PostgreSQL backup
pg_dump -h localhost -p 5433 -U odoo_user -Fc odoo_production > \
    odoo_prod_backup_$(date +%Y%m%d_%H%M%S).dump

# Filestore backup (attachments, images)
tar -czf odoo_filestore_$(date +%Y%m%d).tar.gz \
    /var/lib/odoo/.local/share/Odoo/filestore/

# Configuration backup
cp /etc/odoo/odoo.conf odoo_conf_backup_$(date +%Y%m%d).conf

Custom module code review:

For each custom module, run a compatibility check:

# Check for deprecated patterns
grep -r "execute_kw" custom_modules/   # Still valid in v19
grep -r "browse\(\[" custom_modules/  # Should be browse(ids) not browse([ids])
grep -r "_multi" custom_modules/      # Check for renamed methods
grep -r "account\.move\.line\." custom_modules/  # Account refactoring affected
grep -r "@api\.one" custom_modules/   # Removed in v14, ensure not present
grep -r "@api\.multi" custom_modules/ # Removed in v14, ensure not present

---

Setting Up the Migration Environment (Week 2-3)

Infrastructure setup:

# Install Odoo 19 Enterprise on migration server
# Requirements: Ubuntu 22.04/24.04, PostgreSQL 15+, Python 3.12

# Install PostgreSQL 15+
sudo apt install postgresql-15 postgresql-contrib

# Install Python 3.12 and dependencies
sudo apt install python3.12 python3.12-dev python3.12-venv \
    libxml2-dev libxslt1-dev libldap2-dev libsasl2-dev \
    libtiff5-dev libjpeg8-dev libopenjp2-7-dev zlib1g-dev \
    libfreetype6-dev liblcms2-dev libwebp-dev libharfbuzz-dev \
    libfribidi-dev libxcb1-dev

# Clone Odoo 19 Enterprise
git clone https://github.com/odoo/odoo.git -b 19.0 /opt/odoo19
git clone https://github.com/odoo/enterprise.git -b 19.0 /opt/odoo19-enterprise

# Install Python dependencies
pip3.12 install -r /opt/odoo19/requirements.txt

Restore source database to migration server:

# Create target database
createdb -h localhost -U postgres odoo_migration_test

# Restore backup
pg_restore -h localhost -U postgres -d odoo_migration_test \
    odoo_prod_backup_YYYYMMDD.dump

# Run Odoo upgrade
python3 /opt/odoo19/odoo-bin \
    -d odoo_migration_test \
    -u all \
    --without-demo=all \
    --stop-after-init

---

Custom Module Migration (Weeks 3-5)

This phase is the most time-intensive. Each custom module requires:

1. Update manifest version:

# Change from:
'version': '17.0.1.0.0',
# To:
'version': '19.0.1.0.0',

2. Update Python compatibility:

# Old pattern (deprecated):
@api.multi
def my_method(self):
    for record in self:
        pass

# New pattern:
def my_method(self):
    for record in self:
        pass

3. Update view syntax:

<!-- Old (v16 and earlier): -->
<field name="state" attrs="{'invisible': [('active', '=', False)]}"/>

<!-- New (v17+): -->
<field name="state" invisible="not active"/>

4. Update OWL components (if any frontend widgets):

OWL 3.x introduces reactivity changes. If your modules use custom JavaScript widgets:

// Old OWL 2.x:
class MyWidget extends Component {
    static template = 'MyModule.MyWidget';
    willStart() { ... }
}

// New OWL 3.x:
class MyWidget extends Component {
    static template = 'MyModule.MyWidget';
    setup() {
        onWillStart(async () => { ... });
    }
}

5. Test each module independently:

# Install and test each custom module
python3 odoo-bin -d test_db -i my_custom_module --stop-after-init
python3 odoo-bin -d test_db --test-enable -u my_custom_module

---

Data Validation and Testing (Weeks 5-6)

Financial data validation:

-- Verify balance sheet balances (assets = liabilities + equity)
SELECT
    SUM(CASE WHEN account_type LIKE 'asset%' THEN balance ELSE 0 END) as assets,
    SUM(CASE WHEN account_type LIKE 'liability%' THEN balance ELSE 0 END) as liabilities,
    SUM(CASE WHEN account_type = 'equity' THEN balance ELSE 0 END) as equity
FROM account_account aa
JOIN account_move_line aml ON aml.account_id = aa.id
JOIN account_move am ON aml.move_id = am.id
WHERE am.state = 'posted';

Record count validation:

Compare record counts between source and migrated database:

# Run on both source and target to compare
models_to_check = [
    'res.partner', 'product.template', 'product.product',
    'sale.order', 'purchase.order', 'account.move',
    'stock.quant', 'mrp.production', 'hr.employee'
]

for model in models_to_check:
    count = env[model].search_count([])
    print(f"{model}: {count}")

User acceptance testing checklist:

• All menus and navigation items accessible
• Key workflows: sale order → delivery → invoice → payment
• Accounting: journal entries, bank reconciliation, reports
• Inventory: receipts, deliveries, stock valuation
• Manufacturing: BOM, work orders, quality checks (if applicable)
• HR: employees, leave management, payroll (if applicable)
• Custom module functionality verified by business users
• Reports generate correctly and match pre-migration output
• External integrations (API, webhooks) tested in staging

---

Go-Live Cutover Plan (Week 7-8)

Cutover window planning:

Choose a cutover window with minimal business impact:

• Weekend (Saturday evening to Sunday morning for most businesses)
• End of fiscal month (simplifies opening balance entry)
• After last business day before a bank holiday (extra buffer time)

Cutover checklist:

T-48 hours:
[ ] Final communication to all users about downtime window
[ ] Freeze all non-critical transactions in old system
[ ] Verify migration server is ready
[ ] Complete last data validation run

T-0 (Cutover Start):
[ ] Put old system in maintenance mode (disable user access)
[ ] Create final backup of production database
[ ] Run final migration on this backup
[ ] Verify record counts and financial balances
[ ] Test all critical workflows
[ ] DNS/URL cutover to new system
[ ] Smoke test from user devices (desktop, mobile)

T+2 hours (Go-Live Verification):
[ ] All users can log in
[ ] Create test sale order, confirm, ship, invoice
[ ] Verify email sending works
[ ] Check integrations are receiving/sending data
[ ] Monitor error logs for first 30 minutes

Rollback plan:

If critical issues are found during cutover:

1. Switch DNS back to old server (< 5 minutes)
2. Re-enable old system for users
3. Document all issues found
4. Schedule follow-up migration window

---

Frequently Asked Questions

Can I skip from Odoo 17 directly to Odoo 19, or must I go through 18?

Using Odoo's official upgrade service, you can typically go directly from 17 to 19. Odoo SA's migration scripts handle multi-version jumps. With OpenUpgrade, you may need to go 17→18→19 depending on available migration scripts. Always check the OpenUpgrade repository for the specific versions you need.

How long does a typical Odoo migration take?

Timeline depends heavily on customization level. A standard Odoo instance with minimal customizations: 2-3 weeks. Moderately customized (5-10 custom modules): 4-6 weeks. Heavily customized with complex integrations: 8-16 weeks. The migration itself (database upgrade) takes hours; the time is in testing, module updates, and validation.

What happens to Studio customizations during migration?

Studio customizations are stored as standard Odoo data (views, fields, automations) and migrate through the standard database upgrade process. However, some view customizations may need manual review if Odoo 19 changed the underlying form structure. Always test all Studio customizations post-migration.

Do I need to re-enter opening balances after migration?

No, if you migrate the database directly. All historical journal entries and balances transfer with the database. If you choose the "fresh install with data import" path, you would need to enter opening balances as of the cutover date, which requires careful coordination with your accounting team.

Will my Odoo Enterprise license transfer to version 19?

Yes. Odoo Enterprise subscriptions are version-agnostic. Your annual subscription covers whatever version you run. Contact your Odoo partner to obtain the Odoo 19 Enterprise code if you're not accessing it through Odoo's Git repository with your enterprise credentials.

---

Next Steps

Odoo migrations are high-stakes projects that directly impact business continuity. The difference between a smooth migration and a painful one comes down to preparation, expertise, and a rigorous testing methodology.

ECOSIRE has successfully migrated dozens of Odoo instances from versions 13, 14, 15, 16, 17, and 18 to Odoo 19 Enterprise. Our migration methodology covers full assessment, custom module updates, parallel testing, and a documented cutover plan with rollback procedures.

Request an Odoo Migration Assessment from ECOSIRE →

We'll assess your current environment, identify all migration risks, and provide a fixed-scope migration plan so you know exactly what to expect before the first migration script runs.