Upgrading Odoo Versions: The Migration Runbook
Upgrade Odoo 17, 18 or 19 to Odoo 20: support dates, the 25% fee for old versions, upgrade.odoo.com vs OpenUpgrade, custom modules and cutover.
Key takeaways
- An Odoo upgrade is the process of moving a database from an older version to a newer supported version, for example from Odoo 17.0, 18.0 or 19.0 to Odoo 20.0, or a longer multi-hop such as 16.0 to 20.0.
- Odoo releases a major version once a year and supports each one for three years with helpdesk support, bug fixes and security updates.
- Odoo 17.0 reached the end of standard support in September 2026, the month Odoo 20 shipped.
- The Odoo Upgrade platform at upgrade.odoo.com is the central Enterprise service that transforms a database backup into one that runs on the target version.
What an Odoo version upgrade is, and what it isn't
An Odoo upgrade is the process of moving a database from an older version to a newer supported version, for example from Odoo 17.0, 18.0 or 19.0 to Odoo 20.0, or a longer multi-hop such as 16.0 to 20.0. Odoo's administration documentation frames upgrades as essential because each version delivers features, bug fixes, and security patches, and it recommends running on a supported version. Each major Odoo version receives standard support for three years from its release date.
Separate an upgrade from the other moves people casually call 'migration.' A standard upgrade stays inside Odoo and does not cover four things Odoo lists explicitly: downgrading to a previous version, switching editions (Community to Enterprise), changing hosting type (on-premise to Odoo Online), or migrating from another ERP into Odoo. Each of those is a different project with different tooling and a different risk profile. Community → Enterprise is a licence and package switch on top of (or instead of) a version upgrade. The Upgrade platform does not do it for you as a free side effect.
Inside a true version upgrade there are two layers that break or succeed independently. The standard upgrade is what the Odoo Upgrade platform does to the database itself: it converts standard modules and their data so the database runs on the target version. That path is only available for databases registered with a valid Enterprise subscription. The custom upgrade is the work you must do to make your own modules (anything that extends standard Odoo code and was not built with Studio) compatible with the new version. A database containing custom modules cannot be upgraded until a version of those modules exists for the target Odoo release, which is why the custom upgrade is usually the longest part of the project.
As of October 2026, Odoo 20.0 (released September 2026) is the newest major version, and Odoo 18 and 19 are the other two versions under standard support. Odoo 17.0 left standard support in September 2026. Odoo Online no longer supports it, and Odoo.sh and on-premise databases can stay on it only through extended support, which costs extra. Odoo 16.0 left standard support in September 2025. Plan upgrades against those dates, not against a 'when we have time' backlog.
Odoo's version lifecycle: when you must upgrade
Odoo releases a major version once a year and supports each one for three years with helpdesk support, bug fixes and security updates. After that, extended support is available for an extra fee on Odoo.sh (for a limited number of versions) and on-premise, with no security updates and fixes only where technically feasible. Intermediary SaaS versions ship every two to three months on top of the majors; they exist only on Odoo Online and are not eligible for extended support. Odoo lets you upgrade from any version to any major version still under standard support, or to one that left standard support less than six months ago, which helps when you are late on a hop.
On Odoo Online the upgrade clock is strict. If a database sits on a major version (17.0, 18.0, 19.0), an upgrade is mandatory every two years. If it sits on a minor version (19.1, 19.2, 19.3), an upgrade is mandatory a few weeks after the next version is released. Odoo Online also runs a Rolling Release process: the Upgrade Team performs a silent test upgrade of every database due for upgrade, and if that test succeeds and lasts under 20 minutes you can trigger the upgrade yourself; if you do nothing by the due date, an automatic upgrade to the next version is triggered.
Odoo.sh gives you more runway: after the initial three years of support you have another two years to complete the upgrade, and you are notified when an upgrade is required. On-premise is the most permissive: you can stay on the same version indefinitely, though Odoo advises against it and notes that the smaller the version gap, the easier the upgrade should be. The practical takeaway is that an Odoo upgrade is rarely a surprise: the deadline is published, and planning a major-version upgrade is a project you schedule, not an outage you absorb.
Odoo announced Odoo 20 at Odoo Experience 2026 in Brussels (24 to 26 September 2026), and its support table lists Odoo 20.0 as released in September 2026 with standard support planned to September 2029. The Odoo 20 release notes cover AI agents that create and update records and can run from automated or scheduled actions, a database connection over MCP, offline mode, a step-by-step payroll pay run, and several currencies at checkout in one Point of Sale. Every AI feature in Odoo 20 needs In-App Purchase credits, so budget for them if you plan to use agents. Partners usually wait three to six months after a major launch before large custom production cutovers, while third-party apps catch up; that happened with Odoo 19 after September 2025.
Knowing the support status of your current version is the first planning input. The table below summarises the major-version timeline from Odoo's standard and extended support page (Odoo 20.0 documentation, checked October 2026).
| Version | Release date | End of standard support | Status (October 2026) |
|---|---|---|---|
| Odoo 20.0 | September 2026 | September 2029 (planned) | Newest major; SaaS minors follow on Odoo Online |
| Odoo 19.0 | September 2025 | September 2028 (planned) | Standard support |
| Odoo 18.0 | October 2024 | September 2027 (planned) | Standard support; oldest of the three covered versions |
| Odoo 17.0 | November 2023 | September 2026 | Extended support (extra fee) on Odoo.sh and on-premise; not supported on Online |
| Odoo 16.0 | October 2022 | September 2025 | Extended support (extra fee) on Odoo.sh and on-premise; not supported on Online |
| Odoo 15.0 | October 2021 | October 2024 | Extended support (extra fee) on Odoo.sh and on-premise |
| Odoo 14.0 and older | Before 2021 | Before 2024 | Extended support on-premise only |
Odoo 17 end of support: what changes and when the 25% fee can start
Odoo 17.0 reached the end of standard support in September 2026, the month Odoo 20 shipped. From then on it gets no security updates. On Odoo.sh and on-premise you can pay for extended support, which keeps helpdesk access and bug fixes where they are technically feasible. Odoo Online lists 17.0 as not supported.
The cost of staying is written into the Odoo Enterprise Subscription Agreement. Covered Versions are the three most recently released major versions, now 18, 19 and 20. Once a year, and no earlier than six months after a new major version is released, a database on an older version can be charged an extra 25% of the annualized license, based on the current per-user price and the number of Users and Light Users. Odoo 20 shipped in September 2026, so for an Odoo 17 database that fee cannot start before about March 2027.
For a company of 20 to 100 people on Odoo 17, the choice is usually between one hop to 19, which has a year of fixes and third-party module releases behind it, and a longer hop to 20, which keeps you under standard support a year longer. Either way, start the module inventory now so the test upgrade runs well before March 2027.
| You are on | Standard support ends | Earliest 25% fee if you stay | Suggested move |
|---|---|---|---|
| Odoo 17 | Ended September 2026 | About March 2027 | Plan the upgrade now and move to 19 or 20 before the fee can start |
| Odoo 18 | September 2027 (planned) | Six months after the next major release, about March 2028 on a yearly cadence | Upgrade to 20 during 2027, after your third-party modules have 20.0 releases |
| Odoo 19 | September 2028 (planned) | Not before 2029 on a yearly cadence | Upgrade to 20 once every module you depend on has a 20.0 release |
| Odoo 20 | September 2029 (planned) | None while it is a covered version | Newest version; confirm third-party module support before you start a new project on it |
How the Odoo Upgrade platform works
The Odoo Upgrade platform at upgrade.odoo.com is the central Enterprise service that transforms a database backup into one that runs on the target version. You hand it a copy of your database (and, where relevant, custom module source on your side), and it returns an upgraded database plus an upgrade report that documents the changes the new version introduced. The platform is the same engine regardless of hosting; what changes is the interface you use to reach it. It is not a free public tool: the on-prem CLI and web upload require a registered database with a valid Enterprise subscription (or a contract code). Community databases that hit the script without a subscription receive an error that the subscription code could not be obtained. That is expected, not a misconfiguration.
There are three interfaces. On Odoo Online you upgrade through the database manager: select the database, open Manage, choose Upgrade, pick the target version and purpose (Test first, Production later), and the platform does the rest, emailing you a link to the upgraded database. On Odoo.sh the platform is integrated directly into your project's branches (staging for test, master/production for cutover), and on on-premise you drive it from a command-line script or the Upgrade page upload.
The on-prem CLI is the most explicit view of what the platform expects. You run a script streamed from Odoo on the machine hosting the database, pointing it at the local database and a target version. For a test database the command is `python <(curl -s https://upgrade.odoo.com/upgrade) test -d <your db name> -t <target version>`; for production you replace `test` with `production`. The script requires OS-level command-line tools (present in any normal Linux distribution, including WSL), a system user configured with PostgreSQL access, and network reachability to the upgrade servers on TCP 443 plus a range of random high ports (32768 to 60999) that restrictive firewalls may need to whitelist.
Two details about the platform trip people up. First, for storage reasons the database copy is submitted without its filestore, so the upgraded test database does not contain your production filestore. You must merge the upgraded filestore with your production filestore before you can test in realistic conditions. The upgraded package typically includes a `dump.sql` and a `filestore` folder with files extracted from in-database records plus new standard Odoo assets for the target version. Second, only the person who submitted the upgrade request can download the result, so the request should come from the account that will own the upgraded database. You can request multiple test databases if you need more than one rehearsal cycle.
The standard upgrade workflow, in seven steps
Odoo condenses a standard (non-custom) upgrade into a seven-step nutshell, and every serious upgrade follows this skeleton. Step one: request an upgraded test database. Step two: if you have custom modules, upgrade their source code to be compatible with the target version. Step three: thoroughly test the upgraded database against your real business flows. Step four: report any issue found during testing to Odoo via the support page, selecting the option for an issue related to a future upgrade you are testing.
The remaining steps are the cutover. Step five: once all issues are resolved and you are confident the upgraded database can serve as your main database, plan the production upgrade. Step six: request the production upgrade, which renders the database unavailable for the duration of the process. Step seven: report any issue encountered during or after the production upgrade through the post-upgrade support path. Treating these as two separate reporting channels matters: issues found in test are cheaper to fix and the feedback improves the standard scripts before your production run.
The workflow's hidden assumption is iteration. Because the standard upgrade scripts and your database are both constantly evolving, Odoo recommends requesting fresh upgraded test databases frequently to confirm the process still succeeds, and fully rehearsing the upgrade the day before you cut over production. An upgrade that worked on last month's backup can fail on this month's if new data or a new script interacts badly, so a rehearsal the day before is the cheapest insurance you can buy.
Upgrading custom modules: where upgrades break
If your database has custom modules, the custom upgrade is the part that decides whether the project finishes in weeks or quarters. Odoo defines a custom module as anything that extends standard code and was not built with the Studio app, and it is explicit that a database with custom modules cannot be upgraded until a version of those modules exists for the target Odoo release. The recommended approach is to parallelise: request the upgraded database from the platform while you simultaneously upgrade your custom module source code.
Studio sits in a different bucket. Under the Enterprise SLA, customizations created with Studio are covered by the upgrade service as long as Studio remains installed and the subscription is active, so you do not rewrite Studio fields the way you rewrite Python modules. That coverage does not mean 'ignore Studio.' Before you freeze the codebase, inventory every Studio customization: fields, views, automated actions, and reports that were built for a previous UX. After the standard upgrade, walk those screens in UAT; Studio debt shows up as broken views, redundant fields that the new version now provides natively, and workflows users no longer need. Export or document non-obvious Studio logic so you can rebuild deliberately if a view is disabled in the upgrade report.
Odoo's custom-database upgrade how-to breaks the work into six steps. First, freeze the codebase: ongoing development must stop, because every change you make will need to be re-upgraded and re-tested; bug fixes are the only exception, and this is also the moment to challenge existing customizations and replace them with standard features where possible to reduce technical debt. Second, request the upgraded test database to confirm the standard process itself succeeds. Third, make the custom modules installable on an empty database of the target version. Install them one by one and fix the tracebacks and warnings that surface from invalid dependencies, syntax changes (assets, OWL, attrs), renamed or removed fields, models, and views, and xpaths that moved.
The fourth and fifth steps are where data lives. Once the modules install cleanly on an empty database, you make them work on the upgraded database, which is where data-migration scripts come in (covered in the next section), and you test the custom modules against the upgraded data to confirm nothing was lost. Sixth, you run another full testing and rehearsal pass before production. Writing automated tests during this phase is strongly encouraged, because they shrink the testing iterations across the many times you will re-run the upgrade, and they catch regressions your fixes introduce.
Throughout, keep the goals of an upgrade in view: stay supported, get the latest features, enjoy the performance improvements, reduce technical debt, and benefit from security improvements. A custom upgrade that only makes old code compile on the new version, without removing the customizations the new version now provides natively, pays the cost of the upgrade twice, once in migration effort and again in ongoing maintenance of code you no longer need. AI-assisted module generation has increased the surface area of 'quick custom' code in many fleets; treat generated modules as first-class custom debt and include them in the freeze inventory.
Data migration scripts: rename_field, rename_model, rename_xmlid
When custom code is renamed during an upgrade, the underlying data must be renamed too or it is silently lost. Odoo handles this with upgrade scripts: version-specific Python files that run during the module upgrade to transform live data. They live in a `migrations/<version>/` directory inside a module, with phased entry points (`pre-`, `post-`, and `end-` scripts) that run at different points in the module lifecycle so you can act before or after fields and tables exist.
The upgrade-utils companion library (github.com/odoo/upgrade-util) provides the helper functions you reach for most often. `rename_field`, `rename_model`, and `rename_xmlid` keep references intact when you rename technical identifiers; `recompute_fields` recomputes stored fields whose computation logic changed; `remove_module` cleanly uninstalls modules you are dropping; and `update_record_from_xml` updates `noupdate` data records that are not refreshed by a normal module upgrade. Any technical data renamed in the source-code upgrade should be renamed in the database with these helpers to avoid data loss during the module upgrade.
A canonical example is a model that was merged between versions. Custom fields on `sale.subscription` were not automatically migrated from Odoo 15 to 16, because in 16 that model was merged into `sale.order`. The fix is a `post-` script that runs a SQL query to copy the custom column from the old table to the new one once the target columns exist. Upgrade scripts are also useful for performance (storing the value of expensive computed stored fields via SQL on large tables) and for correcting faulty data or configuration that you do not want to carry forward. On Odoo.sh these scripts run automatically as part of the custom-module update on each commit; on on-premise you run them by deploying the upgraded dump and invoking `odoo-bin -u <modules>` to update the custom modules.
Odoo.sh 'update on commit' mode, explained
Odoo.sh is the hosting type most tightly integrated with the Upgrade platform, and its upgrade mode is built around the way teams develop. When you start an upgrade on a staging branch, Odoo.sh sends the latest production daily automatic backup to the Upgrade platform, not an arbitrary staging dump or a manual backup you selected. Once the platform finishes upgrading that backup and uploads it to the branch, the branch enters a special 'update on commit' mode: every time you push a commit, Odoo.sh restores the upgraded backup and updates all custom modules against it. This lets you test your custom code on a pristine copy of the upgraded database on every change, with the upgrade log available at `~/logs/upgrade.log` in the build.
This commit-driven loop is what makes parallelising the custom upgrade practical. You iterate on your custom module source in version control, and each push triggers a fresh restore-and-update that runs your upgrade scripts, so you get fast feedback on whether a rename or a removed view works against real data. If there are no custom modules, the 'update on commit' mode is skipped entirely: the upgraded database is built as soon as it transfers from the platform, and upgrade mode exits. If you have no custom code changes to push but need to re-trigger the loop, Odoo's Upgrade page guidance notes that you can push an empty commit so the restore-and-update cycle still runs.
Production on Odoo.sh follows the same logic but on the Production branch, and the upgrade is triggered as soon as a new commit is made on that branch so the upgrade stays synchronised with the deployment of your upgraded custom code. The database is unavailable throughout, and the platform automatically reverts the upgrade if anything goes wrong (as it would for a regular update), creating a pre-upgrade backup on success. The one hard requirement: your staging upgrade must show a 'successful' status before you attempt production, because the custom-module update must succeed for the entire upgrade to complete. After a production upgrade, rebuild or re-test staging branches deliberately so they do not lag on old dumps and half-ported modules. Staging discipline after cutover is as important as the cutover itself.
OpenUpgrade: the open-source alternative for Community and on-prem
Not every Odoo database is on Enterprise or hosted by Odoo, and the official Upgrade platform is a paid benefit tied to the Enterprise licence. For Community edition and many self-hosted Community databases the OpenUpgrade project from the Odoo Community Association (OCA) is the open-source alternative. It provides community-maintained upgrade paths between Odoo major versions. Odoo itself has acknowledged OpenUpgrade's importance in contributor documentation, noting the project is arguably as important as Odoo's own code for companies that cannot afford the Enterprise upgrade service. As of 2026 the OpenUpgrade repository maintains 19.0 branches for `openupgrade_framework` and `openupgrade_scripts`, with published module coverage analysis for paths including 18.0 → 19.0.
OpenUpgrade works by shipping migration scripts that transform your database version-to-version on your own infrastructure. Unlike the Enterprise platform, which can take a database from an older major version to a chosen supported target in one platform request, OpenUpgrade is designed around sequential major hops: you migrate 17→18, then 18→19, then 19→20, fixing failures at each step. Coverage is community-maintained (popular apps are usually well covered, niche or newer ones may lag), and there is no Odoo SLA or upgrade report. You own the runtime, the failure modes, and the custom-module scripts. For a heavily customised Community database it is often the only economically viable path; for an Enterprise database on Odoo.sh the official service is almost always the better choice.
Third-party Community tools (for example hosted dump-upload services that advertise multi-version CE migration) appear regularly; treat them as unvetted infrastructure unless your security and compliance reviews approve them. The durable, inspectable default remains OpenUpgrade on infrastructure you control, plus your own custom-module ports. Manual greenfield reinstall with selective data import remains valid for small, clean Community databases where multi-hop cost exceeds rebuild cost.
The decision usually comes down to edition and hosting. If you are on Enterprise with a maintenance-of-customizations subscription, the official Upgrade platform covers your standard apps, your Studio customizations, and your maintained developments at no extra cost, so use it. If you are on Community, or on on-premise Enterprise with substantial third-party modules and no maintenance contract, OpenUpgrade (or a controlled rebuild) is the realistic route, and you should budget for the testing and custom-script work the official service would otherwise handle.
| Dimension | Odoo Upgrade platform | OCA OpenUpgrade |
|---|---|---|
| Who runs it | Odoo's hosted service | You, on your own infrastructure |
| Edition | Enterprise (free with licence) | Community and Enterprise |
| Coverage | Standard apps + maintained customizations | Community-maintained, varies by app/path |
| Custom modules | Covered under maintenance contract | You write and run the scripts |
| SLA / upgrade report | Included | None |
| Cost model | Bundled with Enterprise subscription | Free, but you carry the effort and risk |
Multi-version jumps: 16 or 17 to 20 without wishful thinking
Many databases are not one release behind. They sit on 16 or 17 while leadership wants 20, or on Community 17 while finance wants Enterprise 20. The right strategy depends on edition, not ambition.
On Enterprise with a valid subscription, the Upgrade platform lets you request an upgrade to a supported target version from older majors. Odoo documents upgrades as moving from an older version to a newer supported version, and the target selector lists the supported line, not a forced single-step ladder. That does not make a 17→20 hop easy. It means the standard data conversion can be requested in one platform pass while your custom modules still have to be compatible with the final target. In practice you still inventory every intermediate breaking change that affects your code, even if you never run a production instance on 18 or 19.
On Community with OpenUpgrade, multi-hop is sequential by design: migrate one major at a time, validate, then continue. Skipping a hop is not a supported OpenUpgrade pattern. Budget calendar time per hop, not one heroic weekend for three majors. Coverage analysis matrices (for example 18.0→19.0 module coverage on the OpenUpgrade docs) tell you which standard modules already have scripts and which need manual attention.
Hybrid projects, a Community data path into an Enterprise licence, are edition switches plus version upgrades, not one button. Typical patterns: (1) upgrade Community hop-by-hop with OpenUpgrade to the target major, then switch to Enterprise packages and subscription; or (2) migrate data into a fresh Enterprise database when the custom surface is small. Do not expect upgrade.odoo.com to accept an unregistered Community dump and return a clean Enterprise 20 database without a contract and a defined switch plan.
Rule of thumb for planning: the larger the version gap, the higher the share of work that is custom-module and third-party porting rather than standard conversion. Smaller gaps are cheaper; multi-year gaps are where 'we will just upgrade' becomes a re-implementation project wearing upgrade clothing.
| Situation | Preferred path | What to budget |
|---|---|---|
| Enterprise, one major behind (e.g. 19→20) | Official Upgrade platform + staging UAT | Days to weeks; mostly testing and release-note training |
| Enterprise, multi-major (e.g. 17→20) | One platform target to supported 20 + full custom port | Weeks to months; empty-DB install, scripts, third-party replacements |
| Community, one major behind | OpenUpgrade single hop + custom scripts | Technical owner + sequential UAT |
| Community, multi-major | OpenUpgrade hop-by-hop or selective rebuild | Calendar per hop; do not stack untested majors |
| Community → Enterprise at new major | Version path + edition switch plan | Licence, package install, then Enterprise upgrade hygiene |
Pre-upgrade inventory: Studio, third-party apps, and freeze discipline
The freeze is only as good as the inventory that precedes it. A useful pre-upgrade pack is a spreadsheet or wiki page that every technical owner can open without tribal knowledge.
Module inventory: list every installed module with technical name, author (Odoo SA / Studio / in-house / Odoo Apps third-party / OCA), whether it is under a maintenance contract, and whether a target-version branch or package exists. Flag blockers in red before you request the first production-bound test upgrade. Apps Store modules without a listing for your target version (20.0, for example) are schedule risk, not 'probably fine'.
Studio inventory: list custom fields, views, automated actions, and reports. Note which ones duplicate native capabilities of the target version so you can retire them after upgrade instead of defending them. Confirm Studio remains installed if you rely on SLA coverage for those customizations.
Integration inventory: every EDI feed, payment provider, shipping carrier, eCommerce connector, and internal API client that assumes field names or XML-RPC/JSON-RPC behaviour from the old version. Upgrade neutralization resets payment providers and carriers to test mode on test databases, so plan credentials and sandbox tests explicitly.
Data hygiene (optional, and worth it on large databases): archive or purge true junk before the dump used for late rehearsals, without destroying audit-relevant history. Partners routinely report multi-day conversions dominated by bloated message and logging tables. The Enterprise SLA does not include data cleaning, so it is your project work if you want faster loops.
Success criteria: write the go/no-go checks before UAT starts. Typical checks are trial balance and stock valuation reconciliation, the top ten business flows from order to cash, critical reports (invoice PDF, picking), and 'can we ship and get paid on Monday.' Without written criteria, upgrades end on feelings.
Testing the upgraded database: the checklist that prevents go-live fires
Testing is the most valuable work in an Odoo upgrade, and Odoo is blunt about the consequences of skipping it: going into production without testing can cause users to fail to adjust to changes, business interruptions (such as no longer being able to validate an action), and poor customer experience (an eCommerce site that does not work correctly). The upgraded test database is delivered neutralized for safety. Scheduled actions are disabled, outgoing mail servers are archived and replaced with a fake one, payment providers and delivery carriers are reset to the test environment, and bank synchronization is disabled, so you can exercise real flows without contaminating production.
The basic test checklist Odoo publishes is a starting point, not a finish line. Confirm that views active in production are still active (and that nothing was deactivated during the upgrade), that your usual views render correctly, that reports (invoice, sales order, and so on) generate correctly, that website pages work, that you can create and modify records across sales orders, invoices, purchases, users, contacts, and companies, that mail templates and saved translations are intact, that search filters are still present, and that data exports succeed. Any view that causes problems during upgrade is disabled and listed in the upgrade report, and you must re-activate or remove it.
Full business-flow testing is where you catch the bugs the checklist misses. Odoo's worked example walks a single product through its full lifecycle: check the product's data against production, buy it (Purchase), confirm receipt (Inventory), verify the receipt route matches production, sell it (Sales), inspect the customer record (Contacts), ship it (Inventory), validate the invoice and issue a credit note (Accounting), check report results, spot-check taxes, currencies, bank accounts, and fiscal year, and place an online order through checkout (Website). You then extend that flow to every other app you use. Do not forget external integrations (EDI, APIs), cross-app workflows, automated actions, and server actions on both form views and multi-record list selections.
Two realities shape how you test. First, significant differences in standard views, fields, and models cannot be reverted case by case. If a new-version change breaks a customization, it is the custom module maintainer's responsibility to make it compatible. Second, `noupdate` data records are not refreshed on module upgrade, so custom records that need updating for the new version must be updated via upgrade scripts. Plan your testing around both: verify standard behavior changed intentionally, and verify your custom data was migrated, not just copied.
Production cutover: downtime, filestore, and the rehearsal
The production upgrade is where the project becomes irreversible, so the planning is conservative by design. Your production database is unavailable for the entire duration of the upgrade, so you schedule it for a window of minimal use. Platform conversion time can be minutes for a small, standard database or hours for a large one; the project length is still dominated by custom porting and UAT, not the conversion itself. Because the standard scripts and your database keep evolving, you should request fresh upgraded test databases right up to the cutover to confirm the process still succeeds, and you should fully rehearse the upgrade the day before. A rehearsal is the cheapest way to discover that something in yesterday's data breaks today's run.
The mechanics mirror the test upgrade, with two differences. On Odoo Online you set the purpose to Production instead of Test, and once requested the database is unavailable until the upgrade finishes, and it cannot be reverted to the previous version after completion. On Odoo.sh the production upgrade is triggered by a commit on the Production branch, synchronising the upgrade with the deployment of your upgraded custom code; the database is unavailable throughout, the platform auto-reverts on failure, and a pre-upgrade backup is created on success.
On on-premise the command is the same as the test command with one word changed: `python <(curl -s https://upgrade.odoo.com/upgrade) production -d <your db name> -t <target version>`. Once the database is uploaded, any modification to production will not appear on the upgraded database, which is why you should not use production during the upgrade. The filestore rule from testing applies again and is critical here: the production copy is submitted without a filestore, so before you deploy the new version you must merge the upgraded database's filestore with the production filestore. Missing this step means going live without your attachments, images, and documents.
For multi-hop Enterprise projects (for example 17→20 in one platform target), treat the single production cutover as one freeze window, but expect longer test cycles: more release notes, more renamed identifiers, and more third-party modules that may only have intermediate versions. For Community OpenUpgrade multi-hops, schedule separate staging freezes per major hop so you can stop and fix without stacking three generations of breakage into one weekend.
Common pitfalls and what breaks in an upgrade
Most upgrade pain concentrates in a predictable set of failure modes, and knowing them upfront shortens the project. The first is renamed or removed standard identifiers: fields, models, views, and methods that changed between versions break customizations that reference them, surfacing as tracebacks during module installation on an empty database. The fix is to update the references in your source and, where data is involved, rename it in the database with `rename_field`, `rename_model`, or `rename_xmlid` so existing records stay connected to the new identifiers.
The second is views disabled during the upgrade. When a view causes problems because of its content, the upgrade disables it rather than fail, and the disabled views are listed in the upgrade report. Each disabled view must be re-activated (or removed if it is no longer useful), typically via an upgrade script, and a view that was critical to a daily workflow will silently stop appearing until you catch it in testing. The third is `noupdate` data that does not refresh. Custom records flagged `noupdate` are not updated when the module upgrades in the new database, so any custom data that must change for the new version has to be updated explicitly with `update_record_from_xml` or a script.
The fourth is the filestore. Because the upgraded database is delivered without a filestore, any test or production deployment that forgets to merge the upgraded filestore with the production filestore goes live missing every attachment and image, a failure that is silent in the logs but catastrophic for accounting documents, product images, and signed records. The fifth, and the one most underestimated, is third-party modules without a maintenance contract: the official SLA does not cover them, so if their maintainer has not ported them to the target version your upgrade blocks entirely until you find a replacement or port them yourself. Identifying every third-party dependency and its upgrade status before you freeze the codebase is one of the highest-value planning steps you can take.
The sixth is calendar risk after a major release. Official upgrade scripts for a new major version are not always production-ready on launch day; Odoo has historically finished migration scripts, dogfooded on odoo.com-scale databases, and upgraded Online fleets before opening high-quality paths for everyone. Partner fleets commonly wait weeks to a few months after a September launch before large custom production cutovers. Starting inventory and empty-DB ports early is fine; freezing a production weekend the week of Odoo Experience is usually not. The seventh is assuming Community can 'just run the Enterprise script'. Without a subscription the platform correctly refuses the request.
What the upgrade costs: the Enterprise SLA and its limits
Cost is the question every Odoo customer asks first, and the answer is unusually favourable for Enterprise users. With Odoo Enterprise, upgrading a database to the most recent version of Odoo is free, including any support required to rectify potential discrepancies in the upgraded database. The upgrade service is available for databases hosted on Odoo Online, Odoo.sh, or self-hosted on-premise, so the hosting type does not change the price, only the interface you use to reach it.
What is covered is precise. The SLA covers the upgrade of all standard applications; all customizations created with the Studio app, as long as Studio is still installed and the subscription is active; and all developments and customizations covered by a maintenance-of-customizations subscription. The service is limited to the technical conversion and adaptation of a database (standard modules and data) to make it compatible with the target version. That is a generous scope for a typical Enterprise database.
What is not covered is equally precise and is where budget surprises hide. The SLA does not cover cleaning of pre-existing data and configurations during the upgrade, the upgrade of additional modules not covered by a maintenance contract (whether built in-house or by third parties, including Odoo partners), or training on the new version's features and workflows. Beyond the three-year standard support window, extended support costs extra, and a database outside the three covered versions can be charged 25% of the annualized license once a year. The practical implication is that a database with significant third-party or in-house modules and no maintenance contract will incur real cost to bring those modules under maintenance, port them yourselves, or replace them, and that cost should be estimated before you commit to a target version.
| Covered by the SLA | Not covered by the SLA |
|---|---|
| All standard applications | Cleaning of pre-existing data and configuration |
| Studio customizations (Studio installed, subscription active) | Third-party / in-house modules without a maintenance contract |
| Developments under a maintenance-of-customizations subscription | Training on the upgraded version's features |
| Support to rectify discrepancies in the upgraded database | Extended support beyond three years (extra fee), and the 25% fee for versions outside the three covered ones |
Planning the upgrade: a realistic timeline
A major Odoo upgrade for a database with custom modules is a multi-week project, and the timeline is driven by the custom upgrade, not the standard one. A realistic sequence starts with an inventory: list every installed module, separate standard from Studio, custom, and third-party, and confirm the upgrade status of each third-party module against the target version. In parallel, read the release notes between your current and target versions and challenge your customizations: anything the new version now provides natively should be retired, not ported. This is also when you decide between the official Upgrade platform and OpenUpgrade based on edition and hosting, and whether you are doing a single hop (19→20) or a multi-hop (for example 17→20).
The middle phase is the parallel work: request the first upgraded test database from the platform while you freeze the codebase and begin porting custom modules to install cleanly on an empty database of the target version. Once they install without tracebacks, move to the upgraded database, write the data-migration scripts for any renames or removed models, and start testing your critical business flows from start to finish. Each iteration benefits from a fresh upgraded test database, and on Odoo.sh the 'update on commit' mode gives you that feedback on every push. Slim oversized tables (for example noise in logging or message tables) before large test upgrades when partners recommend it, since smaller dumps shorten feedback loops, without deleting business history you still need for audits.
The final phase is validation and cutover. Re-run the full business-flow test suite against the latest upgraded database, confirm the filestore merge works from upload to deploy, schedule the production window for a low-usage period, and rehearse the upgrade the day before. On go-live, request the production upgrade (set purpose to Production, or push the production commit on Odoo.sh), keep the database unused for the duration, verify the merged filestore after deploy, and report any post-upgrade issue through the post-upgrade support path. If you are already on 19 or 20, keep the same inventory discipline now so the next hop is incremental rather than a multi-year debt dump. For a vendor-neutral view of how this compares to a Dynamics 365 One Version update, our ERP upgrade guide covers the cross-platform cutover, testing, and hypercare patterns that apply to any ERP move.
How Flectic can help
Flectic implements Odoo for companies of 20 to 100 people in the US and Canada and customizes only where your process differs from Odoo's defaults. Flectic sends a written proposal with a fixed price for each phase before work starts. If you are on Odoo 17, that plan covers the module inventory, the choice between 19 and 20, and a cutover date before the 25% fee can start. See how Flectic approaches Odoo projects on the Odoo implementation page. Book a free discovery call to talk through your current version and timing.
Sources
An Odoo upgrade moves a database from an older version to a newer supported version; each major version is supported for three years; upgrade mandates vary by hosting type (Online every two years for major versions / few weeks for minors with Rolling Release, .sh gets three years support plus two more to complete, on-premise can stay indefinitely); standard upgrade does not cover downgrade, edition switch, hosting change, or other-ERP migration; custom modules block upgrade until target-version modules exist.
odoo.comChecked vendor-primaryOn-prem CLI: python <(curl -s https://upgrade.odoo.com/upgrade) test|production -d <db> -t <target>; needs OS tools, PostgreSQL client access, TCP 443 plus ports 32768-60999; copy submitted without filestore; merge upgraded filestore with production; only requester can download; multiple test DBs allowed; upgrade report attached on success.
odoo.comChecked vendor-primaryEnterprise SLA: upgrading to the most recent version is free including support to rectify discrepancies; covers standard apps, Studio customizations (Studio installed, subscription active), and developments under maintenance-of-customizations; does not cover data cleaning, modules without maintenance contract, or training.
odoo.comChecked vendor-primaryOdoo.sh: latest production daily automatic backup sent to Upgrade platform; staging enters update-on-commit (restore upgraded backup + update custom modules each push); log at ~/logs/upgrade.log; production triggered by commit; auto-revert on failure; staging must be successful before production.
odoo.comChecked vendor-primaryTest DBs neutralized: scheduled actions disabled, outgoing mail archived with fake server, payment providers and delivery carriers reset to test, bank sync disabled; basic checklist covers views, reports, website, CRUD, mail templates, translations, filters, exports.
odoo.comChecked vendor-primaryMajor version support (Odoo 20.0 docs): 20.0 released September 2026, standard support planned to September 2029; 19.0 September 2025 (to September 2028); 18.0 October 2024 (to September 2027); 17.0 November 2023 (ended September 2026; extended support on Odoo.sh and on-premise, not supported on Online); 16.0 October 2022 (ended September 2025); upgrade to any major under standard support or one that left it less than six months ago; extended support extra fee, no security updates.
odoo.comChecked 2026-10-20Custom-database upgrade how-to: custom module = extends standard code not built with Studio; six steps include freeze developments, request upgraded DB, install modules on empty target DB, make them work on upgraded DB with migration scripts, test/rehearse, production; upgrade-util helpers include rename_field, rename_model, rename_xmlid, recompute_fields, remove_module, update_record_from_xml.
odoo.comChecked vendor-primaryOfficial upgrade.odoo.com script works only for registered databases with a valid Enterprise subscription; Community has no official automated upgrade path via that service; use OpenUpgrade, manual migration, or other tooling.
odoo.comChecked vendor-communityOCA OpenUpgrade provides open-source upgrade paths between Odoo major versions; documentation covers sequential migration, multi-version strategy, and module coverage including 18.0→19.0; GitHub repo maintains openupgrade_framework and openupgrade_scripts for 19.0.
github.comChecked community-primaryOpenUpgrade documentation site: running migration steps, coverage analysis by version pair, migration file formats for 14.0+.
oca.github.ioChecked community-primaryUpgrade homepage documents CLI test command and Odoo.sh flow: select branch, UPGRADE tab, Test Upgrade / Start Upgrade; staging uses latest daily production backup; push commit (or empty commit) to incorporate customisations after DB upgrade lands.
upgrade.odoo.comChecked vendor-primaryOdoo Experience 2026 (Brussels Expo, 24 to 26 September 2026), where Odoo 20 was presented.
odoo.comChecked vendor-primaryPractitioner/partner discussion: multi-version Community migrations and custom module ports remain multi-week efforts; Odoo 19 upgrade demand is active through 2026; Community OpenUpgrade for 19 is the discussed CE path.
x.comChecked social-signalOdoo 20 release notes (September 2026): all AI features need IAP credits; agents can be triggered by automated and scheduled actions, create and update records; MCP connection to the database; offline mode; payroll pay run workflow; multiple currencies in one POS.
odoo.comChecked 2026-10-20Odoo Enterprise Subscription Agreement: Covered Versions are the 3 most recently released major versions, one new major per year; once per year and no earlier than 6 months after a new major release, a database older than the Covered Versions pays an extra 25% of the annualized price based on Users and Light Users.
odoo.comChecked 2026-10-20
Frequently asked questions
How long does an Odoo version upgrade take?
The platform's actual conversion can take anywhere from minutes to several hours depending on database size, but the surrounding project is much longer. For a database with no custom modules, plan on days of testing between requesting the test database and cutting over production. For a database with custom modules, the custom upgrade (porting code, writing data-migration scripts, and testing) typically runs multiple weeks, and Odoo recommends rehearsing the full upgrade the day before production. Multi-major Community OpenUpgrade paths add calendar time per hop.
When does Odoo 17 support end?
Odoo 17.0 left standard support in September 2026, when Odoo 20 was released. It no longer gets security updates, Odoo Online lists it as not supported, and Odoo.sh and on-premise databases can buy extended support for an extra fee. Under the Enterprise Subscription Agreement, a database outside the three most recent major versions (now 18, 19 and 20) can be charged 25% of the annualized license once a year, no earlier than six months after a new major version ships, so about March 2027 for Odoo 17.
What is the latest Odoo version?
Odoo 20.0, released in September 2026, with standard support planned to September 2029. Odoo 19.0 and 18.0 are the other two versions under standard support. Odoo Online also runs SaaS minor versions between majors (19.3 and 19.4 are still supported there), which never get extended support.
Is upgrading Odoo free?
With Odoo Enterprise, upgrading a database to the most recent version is free, including support to rectify discrepancies in the upgraded database. The SLA covers standard applications, Studio customizations (while Studio is installed and the subscription is active), and developments under a maintenance-of-customizations subscription. It does not cover cleaning pre-existing data, third-party or in-house modules without a maintenance contract, or training. For Community edition, the open-source OCA OpenUpgrade project is free but you carry the effort and risk yourself.
Can I upgrade Community with upgrade.odoo.com?
No. The official script and Upgrade page require a registered database with a valid Enterprise subscription (or contract argument). Community databases get a subscription/eligibility error by design. Community options are OCA OpenUpgrade (sequential major hops on your infrastructure), a controlled rebuild with selective data import, or third-party migration tooling you have security-reviewed. Enterprise → use the official platform.
Can I jump multiple Odoo versions at once (for example 17 to 20)?
On Enterprise, you can request an upgrade to a supported target from an older major; the platform is built around moving to a newer supported version, not forcing you to run every intermediate release in production. You still must make custom modules compatible with the final target and test the full gap. On Community OpenUpgrade, plan sequential hops (17→18→19→20) with validation between steps. Larger gaps almost always mean more custom and third-party work, even when the standard conversion is a single platform request.
Can I downgrade Odoo to a previous version?
No. Odoo's standard upgrade does not cover downgrading to a previous version, and once a production upgrade completes it cannot be reverted to the previous version. This is why testing the upgraded test database and rehearsing the production upgrade are non-negotiable: the decision becomes irreversible the moment production is upgraded. On Odoo.sh the platform does auto-revert if the upgrade itself fails, but a successful upgrade is final.
What happens to my custom modules and Studio customizations?
Custom modules (code that extends standard Odoo outside Studio) must exist for the target version before the database can be upgraded; you port source, write data-migration scripts for renames, and test on empty and upgraded databases. Studio customizations are covered by the Enterprise upgrade SLA while Studio is installed and the subscription is active, but you still UAT every Studio screen and retire debt the new version makes redundant. Third-party modules without maintenance are outside the SLA.
Do I lose my filestore and attachments when I upgrade?
Not if you handle the merge correctly. For storage reasons the database copy is submitted to the Upgrade platform without a filestore, so the upgraded database does not contain your production filestore by default. Before you test or deploy, you must merge the upgraded database's filestore (which includes new standard Odoo files for the target version) with your production filestore. Skipping this step means going live without attachments, images, and documents.
What is the difference between the Odoo Upgrade platform and OpenUpgrade?
The Odoo Upgrade platform is Odoo's hosted Enterprise service, free with a valid Enterprise subscription, covering standard apps and maintained customizations with an SLA and an upgrade report. OpenUpgrade is the OCA's open-source, community-maintained project that provides sequential upgrade paths between major versions and is run on your own infrastructure. OpenUpgrade is the realistic choice for Community edition; for Enterprise databases on Odoo.sh the official platform is almost always preferable.
How does the Odoo.sh upgrade mode work?
On Odoo.sh, starting an upgrade on a staging branch sends the latest production daily automatic backup to the Upgrade platform, and once the upgraded backup is uploaded the branch enters 'update on commit' mode: every push restores the upgraded backup and updates all custom modules, running your upgrade scripts and giving feedback on each change. The upgrade log is at ~/logs/upgrade.log in the build. Production is triggered by a commit on the Production branch, the database is unavailable throughout, and the platform auto-reverts on failure. Staging must show successful before production.
When is an Odoo upgrade mandatory, and should I move to Odoo 20?
Mandates depend on hosting. On Odoo Online, a database on a major version must upgrade every two years, and one on a minor (SaaS) version must upgrade a few weeks after the next version is released; if you take no action by the due date, an automatic upgrade is triggered. On Odoo.sh you have the three years of standard support plus another two years to complete the upgrade. On-premise you can stay on a version indefinitely, though Odoo recommends upgrading. Odoo 20 shipped in September 2026. Move to it once every third-party module you depend on has a 20.0 release; if you are on Odoo 17, upgrade to 19 or 20 before about March 2027, when the 25% fee for old versions can start.
When are upgrade scripts available after a new major release?
Scripts are not guaranteed production-ready on the conference launch day. Odoo finishes migration scripts, validates them on large internal and Online fleets, then opens paths for customers. For Odoo 19, public discussion after the September 2025 launch pointed to a multi-week to multi-month window before confident mass availability. Start inventory and empty-DB ports early; schedule production cutovers after your staging upgrade is green on current scripts, not on the marketing calendar.