Skip to main content
Odoo

How to plan an ERP migration without guesswork.

A migration plan is a set of verified assumptions and rehearsed steps. Here's how to turn the unknowns into a checklist, whether you're moving from a legacy system to Odoo or from one Odoo version to the next.

By Anvexis Stack Engineering8 min read

Two kinds of migration, one discipline

There are two common migrations. A system switch moves you from a legacy ERP, accounting package, or spreadsheet estate into Odoo. A version upgrade moves an existing Odoo database to a newer release. They differ in the details, but they fail the same way: unknowns treated as footnotes instead of work.

Version upgrades are not optional forever. Odoo supports each major version for three years, and on Odoo Online a major upgrade is mandatory every two yearsSource [2]. Plan them as regular, budgeted projects rather than emergencies triggered by an end-of-support email.

The migration planning framework

  1. Inventory

    List every module, customization, integration, report, and scheduled job, with an owner and a criticality for each. Surprises hide in cron.

  2. Profile the data

    Count records, find duplicates and orphans, and identify fields nobody uses. Numbers beat impressions.

  3. Decide what moves

    Full history, open transactions only, or summarized balances, decided per data type with the people who use it.

  4. Rehearse

    Run the full migration on a copy at least twice. Time every step. Reconcile the result.

  5. Communicate

    Freeze windows, training dates, and the rollback trigger, agreed with every team in writing.

Start with an honest inventory

Every migration plan begins with knowing what you're moving. List the modules in use, custom code, integrations, reports, scheduled jobs, and the data volumes behind each. Note who owns each piece and how critical it is to daily operations.

This inventory almost always surfaces surprises: a forgotten integration a warehouse depends on, a custom report finance can't live without, or modules installed years ago and never used. Finding them early turns surprises into planned work, with an owner and a date, instead of a risk line on a slide nobody reads.

Freeze the code and challenge every customization

Odoo's guide to upgrading a customized database lists six steps, and the first is to stop the developments and challenge themSource [1]. It recommends a complete freeze of the codebase while the upgrade is underway, with bug fixes the only exception, and suggests comparing your custom developments against the target version's features to find functional workaroundsSource [1].

That comparison is where upgrades get cheaper. Features you paid to build years ago may now be standard. Every custom module you can retire is one less module to port, test, and maintain. Odoo is clear that a database with custom modules cannot be upgraded until a version of those modules exists for the target releaseSource [2], so the custom code is often the critical path.

Port custom code deliberately

The modules you keep rarely move between major versions unchanged. APIs change, fields are renamed, and the web client may work differently. Odoo's process is to make each module installable on an empty database of the target version first, then installable on the upgraded database, and only then to test extensively and rehearseSource [1].

Test more than installation. The guide calls out views, email templates, reports, server and automated actions, changes to standard workflows, and computed fields as things to check at runtime, and recommends automated tests that pass on the new versionSource [1]. This is also the moment to remove any core patches and rebuild them as proper extensions, which makes the next upgrade cheaper still.

Decide what not to migrate

A migration is the best chance you'll get to leave things behind. Ten years of closed transactions may be better archived in a read-only system than migrated record by record. Old custom fields that nobody fills in don't need a new home.

Agree with each department what history they actually need in the new system, and for how long, considering legal retention rules. Less data means faster migrations, shorter rehearsals, and a cleaner start. For system switches, migrating open transactions plus opening balances is often enough, with the old system kept read-only for look-ups.

Integrations need their own cut-over plan

Integrations are where frozen systems leak. While the old ERP is frozen, the online shop keeps taking orders, the bank keeps sending statements, and the carrier keeps updating shipments. Decide for each integration whether it pauses and queues, keeps writing to the old system for later replay, or switches to the new system at a fixed moment.

Rehearse the switch along with the data migration, including replaying anything queued during the freeze. Then check for duplicates afterwards, because a retried message that lands in both systems is the classic cut-over bug. Integrations built to be idempotent make this far less stressful.

The rollback trigger

Decide in advance which failures trigger a rollback and who makes the call. Deciding during the cut-over night is how bad decisions get made at 2 a.m.

Rehearse until it is boring

The first trial migration always fails in some way: a field mapping is wrong, a custom module won't install, or a data transformation takes far longer than expected. That's exactly why you rehearse. For version upgrades, Odoo strongly recommends requesting an upgraded test database first and spending time testing it before the production upgradeSource [2].

Run full rehearsals on a copy of production data, time each step, and have key users test real workflows on the result. Keep rehearsing until the process is predictable and the timings fit your planned cut-over window. Remember that the production upgrade makes the database unavailable while it runsSource [2], so the timing of the last rehearsal tells you how long the business will be offline.

Validate with numbers, not impressions

Users clicking through a few screens won't spot a missing invoice line or a stock difference of a few units. Before go-live, reconcile key figures between the old and new systems: customer and supplier balances, stock quantities and values, open orders, and the trial balance. Every difference should be explained or fixed.

Automate these checks as scripts during rehearsals, so they run in minutes each time. On cut-over weekend, the same scripts give the go or no-go decision a factual basis rather than a gut feeling.

A typical cut-over timeline

WhenWhat happensOwner
Two weeks beforeFinal rehearsal; timings and reconciliation signed offProject lead
One week beforeFreeze dates confirmed; users trained on the new flowsDepartment champions
Friday eveningOld system frozen; final backup taken and verifiedIT
SaturdayMigration run; reconciliation scripts executedMigration team
SundayKey users test real workflows; go or no-go decisionProject owner
MondayGo-live with hypercare: daily check-ins and fast fixesWhole team

Cut-over checklist essentials

  • Old system frozen at an agreed time
  • Final backup taken and restore-tested
  • Migration run with timings recorded
  • Key totals reconciled: stock, receivables, payables, trial balance
  • Key users sign off on real workflows
  • Rollback criteria, owner, and tested rollback plan confirmed

Choose the right moment

Timing matters as much as preparation. Avoid migrating just before a financial year end, a seasonal peak, an audit, or a major promotion, when the business has no capacity to absorb small problems. Many companies pick a quiet period early in a month or quarter, giving the team time to settle before the next close.

Check the calendars of key people, too. A migration weekend without the finance lead or the warehouse manager available is a weekend where decisions wait, and waiting is the one thing a cut-over can't afford.

Communicate early and often

Migrations affect everyone who uses the system, so tell people what's changing, when, and what they need to do. Share the timeline, the freeze period, and where to get help. Silence breeds rumours; regular short updates build confidence.

Be specific about the freeze. “The old system stops accepting changes at 6 p.m. Friday” is a plan. “We'll switch over at the weekend” is a wish.

Plan the first weeks after go-live

Expect a period of adjustment. Users find differences, reports need tweaking, and a few edge cases appear that no rehearsal covered. Keep the project team available, run daily check-ins for the first weeks, and fix issues quickly so confidence builds instead of eroding.

Keep the old system available in read-only mode for reference during this period. Being able to check how something was recorded before the migration settles many questions in seconds. Our article on why Odoo implementations fail covers the organizational side of this period in more depth.

Budget time for the unexpected

Every migration uncovers something nobody planned for: an obscure customization, a data quirk, or a report that turns out to be essential. Build a contingency into the plan, in both time and budget, and use the rehearsals to shrink the unknowns as early as possible. A contingency you don't spend is good news; one you didn't plan is a missed go-live.

Backups deserve the same respect. A backup you've never restored is a hope, not a plan, which is why restore tests are part of our backup and disaster recovery work and why the cut-over checklist above says restore-tested, not just taken. If you'd like help running the whole process, our migration service follows this framework end to end.

Frequently asked questions

How long does an Odoo version upgrade take?
It depends mostly on the amount of custom code and data. A lightly customized database can move in a few weeks including testing; heavily customized ones take longer because every module must be ported and tested on the target version firstSource [1].
Can we skip versions when upgrading Odoo?
Odoo's upgrade service upgrades the database to the target version you request, but your custom modules still need to be ported to that version, and the further you jump, the more each module changes. Plan the custom-code work accordinglySource [2].
Should we migrate all our historical data?
Usually not. Migrate open transactions, opening balances, and the history people genuinely use, and keep the old system read-only for the rest, within your legal retention rules. Less data means faster rehearsals and a cleaner start.
What should trigger a rollback?
Agree it in advance: for example, reconciliation differences that can't be explained within an agreed time, a critical workflow that can't be completed, or an integration that can't be restored. Name the person who decides, and test the rollback itself during rehearsals.

Sources

  1. [1]Upgrade a customized database, Odoo 18.0 documentation (opens in a new tab)Odoo S.A.
  2. [2]Upgrade, Odoo 18.0 documentation (opens in a new tab)Odoo S.A.

Written by Anvexis Stack

We build Odoo, AI, web, and cloud systems for growing companies, and we write about the patterns we use. This is engineering guidance, not a product guarantee: check vendor details for your version before you decide. Last reviewed .