How Odoo Migration Works A Step-by-Step Guide

What Is Odoo Migration and Why Does It Matter?

Odoo migration is the process of moving your business from one version of Odoo to another or from Odoo Community to Odoo Enterprise while keeping all your data, customisations, and workflows intact. It is not a software update. It is a planned project that touches your database, your custom code, your integrations, and your business processes.

Businesses migrate for different reasons: the current version is reaching end-of-life, a needed feature only exists in a newer version, or the gap between what Odoo can now do and what your version does has become too large to ignore. Whatever the reason, the process itself follows the same logic.

This guide walks through that process in full what each phase involves, what decisions you face at each step, and what goes wrong when those steps are skipped.

Why Migration Is Not Like a Software Update

Every major Odoo version involves significant changes to the database schema, the structure of how data is stored. A field that existed in Odoo 14 may be renamed, split into two fields, or moved to a different model entirely in Odoo 17. A module that worked in the old framework may not be compatible with the new Python version or ORM layer.

This means your data cannot simply be imported into the new version. It has to be transformed and mapped from the old structure into the new one, field by field, record by record, with validation at every step. Custom code has to be reviewed and rewritten where the framework has changed. Third-party integrations have to be tested against the new API endpoints.

The complexity scales with how long you have been on the current version, how much customisation has been done, and how clean your data is.

Key point: The jump from Odoo 14 to Odoo 17 is not three years of updates. It is three major schema changes, multiple framework rewrites, and often a new Python version. Each gap you skip adds to the transformation scope.

Step 1:  Audit: Know Exactly What You Have

Nothing in a migration should come as a surprise. Before any technical work starts, you need a complete picture of your current system.

What the audit covers

1. Your current Odoo version and whether it is Community or Enterprise, determines what upgrade path is available to you
2. Every installed module, including custom ones added by previous consultants, that may not be documented
3. Database size and record counts per model - this directly affects how long the migration will take
4. Data quality  duplicate records, missing required fields, orphaned records that reference deleted entries
5. Every integration with external systems what connects to Odoo, through what method, and who owns those systems
6. The five to ten workflows that absolutely cannot break on go-live - these become the acceptance criteria for the entire project

The audit produces a scope document. This document answers: what needs to be migrated, what needs to be rebuilt, what can be retired because a newer version handles it natively, and what the risks are. Everything that comes after depends on this document being accurate.

Common mistake: Skipping the audit to save time. Without it, scope is guesswork. Customisations surface mid-migration. Data problems appear during import and halt the project. The time saved at the start is lost three times over.

Step 2:  Version and Edition Decision

Once you know what you have, you choose where you are going. This involves two separate decisions.

Which version to target

Migrating to the latest version gives you the longest runway before your next migration. But a larger version gap means more schema changes, more custom module work, and a longer testing phase. Migrating to an intermediate version is sometimes the right call if specific features or a tighter timeline are the priority.

The general principle: if you are more than two major versions behind, migrate directly to the latest stable release. A phased approach through intermediate versions doubles your migration cost.

Community or Enterprise

If you are currently on Community, migration is the natural moment to evaluate whether Enterprise makes sense. The cost of switching edition is marginal when you are already rebuilding your environment  it is significantly higher if you try to switch later as a separate project.

The Community vs Enterprise decision involves more than just pricing. Licensing model, feature access, support, and the total cost of third-party modules all factor in. We have covered this in full in: Odoo Community vs Enterprise: Which Is Right for Your Business and How to Migrate 2026

Step 3:  Data Audit and Cleaning

Data problems are far cheaper to fix in your current system, which your team knows well, than in a new one. Before migration begins, the source data should be audited and cleaned.

What data problems typically look like

1. Duplicate customer and vendor records are common in businesses that have not enforced deduplication. 10 to 20 percent duplication is not unusual in systems older than three years
2. Products missing unit of measure, cost, or category  fields that may have been optional in an older version but are required in the target version
3. Journal entries with unbalanced amounts or missing partner links
4. Open sales or purchase orders referencing products or partners that have been deleted
5. Inventory lots or serial numbers with no product assignment

Migrating bad data does not fix it. It moves it to a new system where it causes the same problems  except now the team is also learning a new interface at the same time.

Data cleaning should result in a simple report: records cleaned, records archived, records migrated as-is with a flag for post-migration review.

Step 4:  Module Assessment

Every custom module and every third-party app in your system needs individual assessment. Modules do not automatically work in the new version. The Odoo framework changes between major versions: functions are deprecated, models are restructured, views are rewritten.

How modules are categorised

1. Migrate as-is: Standard Odoo modules that upgrade cleanly through the version migration tool.
2. Refactor: Custom modules that work correctly but need code updates to match the new framework, deprecated function calls, renamed fields, updated view syntax.
3. Rebuild: Custom modules too deeply tied to the old schema to port efficiently, faster and cleaner to rewrite from scratch in the new version.
4. Retire: Modules solving problems that the newer Odoo version handles natively, replacing them with built-in functionality removes a maintenance burden and reduces cost.

The module assessment drives a significant portion of project cost and timeline. A system with three refactors and one retire has a completely different scope than one with two full rebuilds.

Third-party modules from the Odoo App Store may or may not have a release for your target version. If they do not, you either find an alternative app, replicate the functionality with custom development, or accept losing that feature; each is a business decision, not a technical one.

Step 5:  Migration Execution in a Staging Environment

The actual migration never runs in production. It runs in a staging environment that mirrors production, same server specs, same module list, same configuration.

What happens during migration execution

1. The database is exported from the current production system
2. Migration scripts transform the data from the old schema to the new, renaming fields, restructuring models, and converting data formats that changed between versions
3. All standard modules are installed and configured in the new version
4. Custom and third-party modules  refactored or rebuilt  are installed and tested
5. Data is imported and validated: record counts checked, financial totals reconciled, relationship integrity verified
6. Any records that fail validation are logged, investigated, and either corrected or handled with an exception process

The first migration run will almost always find problems. A field that needs to be not-null in the new version has empty values in 200 records. A foreign key points to a record that was deleted. These are expected, not failures. The process is to find them in staging, fix them, and run again until the migration completes cleanly.

Realistic expectation: Most migrations require two to three staging runs before the data imports without errors. Each run is faster than the last because the fixes reduce the problem set.

Step 6:  Integration Testing

Once data and modules are in the staging environment, every business workflow is tested end to end. Not individual features complete workflows from start to finish.

What end-to-end testing covers

1. Sales: quotation created, confirmed as order, delivery triggered, delivery validated, invoice generated, payment recorded
2. Purchasing: RFQ sent, purchase order confirmed, goods received, vendor bill created, payment made
3. Inventory: stock receipts, internal transfers, outgoing deliveries, adjustments, lot and serial traceability
4. Accounting: journal entries, bank statement import, reconciliation, tax reports, period close
5. All custom workflows specific to that business

Every issue found here is fixed before UAT begins. The goal is that when real users test the system, they are finding edge cases, not broken core workflows.

For businesses in manufacturing, this phase is substantially longer. Work orders, bills of materials, production orders, quality checks, and routing all need dedicated testing. The interdependencies between manufacturing and inventory create failure points that simpler businesses do not have.

Manufacturing migration has its own category of challenges. If you are in manufacturing, read: Odoo Migration for Manufacturing Companies  Challenges, Risks, and How to Get It Right 2026

Step 7:  User Acceptance Testing

UAT is run by the business team, not by technical consultants. This distinction matters. Your team knows things that no tester can discover: the report column that finance uses every week, the shortcut that saves the warehouse team thirty minutes a day, the edge case that only happens with a specific supplier.

How to run UAT effectively

1. Give each department a structured test script covering their critical workflows, not a list of features, but a list of things they actually do
2. Have them use real data or realistic test data, not simplified scenarios
3. Use a structured issue log every bug reported should include the steps to reproduce it, the expected result, and what actually happened
4. Set a defined UAT window with a fixed end date, open-ended UAT drifts
5. Get a sign-off from each department head before go-live is confirmed

What UAT is not: UAT is not the time to request new features. It is the time to confirm that existing workflows work correctly in the new version. New requirements discovered during UAT should be logged separately and addressed after go-live.

Step 8:  Go-Live Planning and Cut-Over

Go-live is a planned operation, not an event. The cut-over plan is written before go-live day arrives, and everyone involved knows exactly what they are responsible for.

What a cut-over plan covers

1. The freeze point on the old system is after this date and time; no new transactions are entered in the old system
2. The delta migration of any data entered between the last staging run and the freeze point needs to be captured and migrated
3. The go-live sequence  order of steps, who does what, and at what time
4. User access switching  when users are redirected to the new system
5. A rollback trigger defines conditions under which you revert to the old system and exactly how that works
6. A communication plan so that every user knows what is happening, when, and who to contact if something is wrong

Go-live timing matters. The safest go-live is on a Monday at the start of a low-activity week, after a freeze on the old system over the weekend. This gives a full business day of live operation before any reporting or period-close obligations create pressure.

Avoid going live at month-end, quarter-end, or during any peak business period. The cost of a delayed go-live is always smaller than the cost of a bad go-live at the wrong moment.

Step 9:  Post-Migration Stabilisation

Migration does not end at go-live. The first two to four weeks of live operation are the period when issues that no testing catches will surface, edge cases in real data, workflows that work in testing but behave differently under production volume, user confusion about changed interfaces.

What stabilisation involves

1. A dedicated support window with fast response times; production issues cannot wait in the normal ticket queue
2. Active monitoring of system performance under real load
3. Daily check-ins with department leads during the first week
4. User training for teams struggling with changed interfaces or new workflows
5. Fixing issues that surface as part of the migration project, not as new change requests

The stabilisation period is also when you confirm that your go-live was genuinely successful: financial data reconciled correctly, period-end close completed normally, integrations operating under real transaction volumes.

Thinking About Odoo 19?

If you are evaluating whether to migrate directly to Odoo 19 rather than an earlier version, the version decision needs to account for what changed in 19 and whether those changes are relevant to your business.

The features introduced in Odoo 19  and how to calculate whether the upgrade ROI justifies the migration scope are covered in: Why Upgrade to Odoo 19? Key Features, Benefits, and Migration ROI [2026]

If you have already decided on Odoo 19 and want a structured checklist to work from before starting: Odoo 19 Migration Checklist: Best Practices for a Risk-Free Upgrade