Upgrading an instance to a newer Odoo version
An upgrade moves the databases of an instance to a newer Odoo major version. You prepare it once, rehearse it on copies of production as often as you need, and then upgrade production. Nothing touches production until that last step.
All of it is on the instance's Upgrade tab and under ohm instance upgrade. Every action is a
job.
This is not the same as changing the Version on the Configuration tab, which leaves the databases as they are. See Changing the Odoo version.
The two engines
The instance's edition decides the engine. There is nothing to choose.
| Enterprise | Community | |
|---|---|---|
| Engine | Odoo's upgrade service | OpenUpgrade |
| Steps | One request, whatever the distance | One step per version; one run can cross several versions |
| Target versions | Every newer version this server offers | Up to 19.0: Community stops there |
| Where it runs | At Odoo S.A. The database is sent there | On this server |
| What a run leaves | Odoo's upgrade report and a log | A log, and no Odoo report |
| What it needs | A valid Odoo subscription and a direct connection | A database within the license's size limit |
An instance with nowhere to go, a Community instance on 19.0 for example, shows There is no newer Odoo version to upgrade to.
Before you start
- A Professional or Provider license. Upgrades come with those two editions only. See Limits by edition.
- Room for one more instance. A prepared instance is an instance, and preparing one is refused when the license's instance limit is reached.
- Disk. A run needs about five times the size of the databases with their filestores free on the backup volume. A rehearsal and a production upgrade both refuse to start without it. The newest rehearsal's upgraded dump stays there after the run, and a production upgrade adds a backup of production.
- The Production role. Rehearsals run for any instance, but only an instance whose Role is Production can be upgraded as production.
A developer workstation does not upgrade databases: it holds neutralized copies.
Enterprise: what is sent to Odoo S.A.
Only the database goes to Odoo. The filestore stays on your server. What comes back is the upgraded database, whatever filestore files Odoo returns, laid over yours, its report and its log.
The database is sent for every full rehearsal and for the production upgrade. Re-running your modules sends nothing.
Odoo's service needs the subscription code that is in the database. A database without one is refused with the reason: register it with its subscription first.
The console asks once per upgrade: Sent to Odoo S.A., a switch on the Rehearse card that
reads I confirm the database is sent to Odoo S.A. for this upgrade. Rehearse and Upgrade
production stay off until it is on, and it is not asked again for this plan. On the command line
the same confirmation is --confirm-odoo-transfer.
Enterprise: the connection
Odoo's upgrade service needs a direct connection from this server to Odoo's upgrade servers,
upgrade.odoo.com first: port 443 and ports 32768 to 60999.
- An HTTP proxy cannot carry them. A server with an outbound proxy set is refused, whatever its firewall allows: upgrade from a server without one.
- The pre-flight tests port 443 only. Nothing listens on the high ports until Odoo has opened a request, so they cannot be tested ahead.
- A blocked high port shows up in a rehearsal, as a failed run. A rehearsal on this server makes the same transfer the production upgrade will make, which is one more reason to rehearse before production is stopped. A rehearsal on another server says nothing about the road from production's own.
Community: what the server fetches
OpenUpgrade comes from GitHub, at a fixed commit for each version. A run across several versions also pulls Odoo's image of each version in between from Docker Hub, and the first run on a server installs a small Python package from PyPI. See What the server reaches.
Preparing the upgrade
On the production instance's Upgrade tab, the Prepare upgrade card:
| Option | What it is |
|---|---|
| Target version | The version to move to. Community can cross several versions in one run |
| Prepared instance is | Test or Staging: what the rehearsals' databases are, as the presets of those names |
Prepare upgrade creates the prepared instance: a new instance at the target version, configuration only, with no database yet, linked to production. Nothing of production changes.
It takes production's edition, classification, custom modules, git configuration, packages and
image source, and starts every custom module at its branch head. It gets a name of its own, unless
--fqdn sets one on the command line. Its Role is Staging, its automatic git updates are off, and
its restore mode is Manual with production as an Instance source, left out of any schedule.
The tab then shows the Upgrade plan card, on both instances: From, To, Engine, Prepared instance and Production.
The rest is the developer's. On the prepared instance, switch the custom modules to their branches for the target version on the Modules tab, and change its packages and settings as the new version needs. The first rehearsal installs the instance as it then stands.
A plan cannot be prepared from a prepared instance, or from an old production kept as a rollback. An instance that has a plan already says which instance holds it: remove that instance to start over. A finished upgrade ends its plan, and the next one can then be prepared: see After the upgrade.
Custom-module branches
Each OpenUpgrade step runs on its own version's code, so a Community jump across several versions needs each custom module on a branch for every step on the way. The Custom-module branches card appears for such a plan, and only then: an Enterprise plan is one step, and so is a Community jump of one version.
Each row is a module and a version in between, filled in with the version's name, such as 18.0.
Change what differs and press Save. The last step is the prepared instance's own, so it is not
listed.
A run refuses to start while a module has no branch, or a branch that is not on its remote. Give the module its branch, or uninstall the module from the databases first.
A step in between runs on Odoo's plain image for that version, without the instance's packages.
Rehearsing
A rehearsal runs only in the prepared instance and never touches production: no host names, no backup settings, no mail or certificate changes, and production is never stopped. Its data is only read.
On the Rehearse card, Take the copy from says where the copy comes from:
| Choice | What it does |
|---|---|
| A fresh copy of production | A new copy of every Odoo database of production, taken from the running instance. The default |
| Its latest local backup | Production's newest backup on this server. Without one, the rehearsal takes a fresh copy instead |
Rehearse then:
- Checks the disk.
- Installs the prepared instance at its current configuration, fetches its modules, and stops it. Whatever an earlier rehearsal left in it is dropped, so every run starts from an empty instance. The branches of any step in between are then checked against their remotes.
- Takes the copy of production.
- Runs the standard upgrade: Odoo's upgrade service, or the OpenUpgrade steps.
- Restores the result into the prepared instance.
- Runs your custom modules, updating every module in each database on the prepared instance's own code.
- Neutralizes the databases, applies the Test or Staging options and marker, and gives each database an identity of its own.
- Activates the database that is active on production, and starts the instance.
The prepared instance then runs as a test copy, on its own name, for as long as you want to test it. Rehearse as often as you need: a rehearsal that succeeds drops the dumps of the ones before it.
Re-run my modules
Re-run my modules is the fast loop for whoever migrates the custom modules. It repeats what comes after the standard upgrade, from the dump the last rehearsal stored, with your modules as they now are on the prepared instance. Nothing is sent to Odoo and no OpenUpgrade runs.
It does not count as a full rehearsal, because it proves your modules and nothing else. Once your modules are right, run Rehearse again before you upgrade production.
The button is on as soon as a rehearsal has stored a dump, which it does once the standard upgrade is
through, so it also works after a rehearsal that failed on your modules. ohm instance upgrade rerun
follows the same rule.
Reading the result
The Rehearsal history card lists every run of the plan, newest first:
| Column | What it shows |
|---|---|
| Started | When the run started |
| Run | Full rehearsal, Modules again, Promote, In place or Rollback |
| Outcome | Running, Succeeded, Failed or RolledBack: a production upgrade that failed and went back by itself, with production running again as it was. One whose way back did not finish is Failed: see When the way back fails too |
| Took | The standard upgrade and the custom-module pass together |
| What it said | The run's summary, or why it failed |
The last column has a button per database, for a production upgrade as well as a rehearsal:
- Odoo's upgrade report, for an Enterprise run. It is Odoo's own page, shown in the console. Read it before you trust a green run: it is what Odoo has to say about your database.
- The upgrade's log, for both engines.
A Community run has a log and no Odoo report. It writes one log per step, named after the step, and the button opens the last one the run reached.
A failed Enterprise request appears as a failed run, whose message names its log on the instance's Logs tab. Odoo's script ends normally even when a request fails, so the proof of success is the upgraded database coming back. A run that did not get one back is failed, whatever the script said.
A run's files are on the Logs tab of the prepared instance, those of a production upgrade too.
Modules OpenUpgrade does not cover
A Community rehearsal reads OpenUpgrade's table of every step and compares it with the modules installed in each database. It does not stop for a module the table leaves open: it says so, and Rehearsal history lists them under OpenUpgrade does not cover:.
A production upgrade is refused while any remain. Uninstall them from production, or wait until OpenUpgrade covers them, and rehearse again. One installed in production after the rehearsal is found before production stops, read from production while it runs, and refuses the run the same way.
A module the table does not list at all, a custom or third-party module, is not reported: it is yours to migrate.
Rehearsing a production on another server
An instance here can rehearse the upgrade of a production on another registered server. This is rehearsal only: to upgrade production, prepare the upgrade on production's own server.
It is for administrators, because the copy that travels carries readable credentials. Make the instance yourself on this server, at the target version, and give it an Instance source that names production on the other server. Its Upgrade tab then has the card Rehearse a production on another server: choose the Instance source and press Use as prepared instance.
Every rehearsal then fetches a fresh copy from the other server, which stops nothing there. Take
the copy from is therefore not offered, and on the command line --copy-from and --max-age-days
do not apply. The other server must run this release, and this server's PostgreSQL must be its version
or newer. The disk is checked once the copy has arrived, at about five times its size: a copy with
no room is refused and deleted before anything is restored.
Upgrade production is refused on such a plan, and the card says why.
Upgrading production
Both ways stop production, so plan a window.
What has to be true
The newest full rehearsal has to be green, on the same target version, on the same custom-module commits the prepared instance holds now, with no module left uncovered. Re-run my modules does not count, and moving a module after the rehearsal means rehearsing again.
While that is not so, the Upgrade production card shows why instead of its button:
| The card says | What to do |
|---|---|
| Production cannot be upgraded before a full rehearsal has succeeded. Re-running the modules does not count. | Run Rehearse |
| The latest full rehearsal did not succeed. Rehearse again first. | Fix what failed, and run Rehearse |
| These custom modules are on another commit than the latest full rehearsal, so it says nothing about them | Run Rehearse on these commits |
| OpenUpgrade does not cover these installed modules, so production cannot be upgraded | See Modules OpenUpgrade does not cover |
| The prepared instance is on another server than production, which is for rehearsals. | Prepare the upgrade on production's own server |
| This upgrade was done: the prepared instance is production now. | Nothing. It is done |
| This upgrade was done: production moved to the target version. | Nothing. It is done. See After the upgrade |
Before production is stopped, the upgrade checks everything it can read while production runs, so a run that cannot work is refused with no downtime:
- this rule, the license, the disk, and that production holds an Odoo database on the plan's version;
- for an Enterprise instance, the road to Odoo, the helper image, and the subscription code of each database;
- for a Community instance, the size of each database, every step's branches and tools, and the modules OpenUpgrade does not cover, a module installed since the rehearsal included.
What it cannot ask in advance is the work itself: the pinned backup, the copy, the standard upgrade with Odoo's high transfer ports, and your modules. Those run after the stop. A failure in the backup, the copy or the standard upgrade ends with production started again as it was.
Promote or in place
How chooses the way:
| Promote the prepared instance (the default) | In place | |
|---|---|---|
| Which instance is production afterwards | The prepared instance. It keeps its own id and takes production's identity | The same instance, at the new version |
| What it does | Upgrades a copy, restores it into the prepared instance, runs your modules, then moves the host names, certificate, backup settings and mail across | Upgrades a copy, gives production the prepared instance's version, module branches, packages and image settings, rebuilds its image, replaces its databases with the upgraded ones under their own names, and runs your modules |
| Downtime | From the stop until the prepared instance answers: the backup, the copy, the standard upgrade, the restore and your modules | The same, plus the rebuild of production's image |
| If it fails | Production's own database was only read. It starts again as it was, and if the names had moved, they move back | Production goes back to its pinned backup by itself |
| The way back afterwards | The old production, stopped and kept | The pinned backup |
Both start the same way: production stops, a full pinned backup of it is made in the upgrade's own area, out of reach of backup retention and of your backup targets, and a fresh copy is taken from the stopped instance. Unlike a rehearsal, the upgraded databases are not neutralized and keep production's identity and subscription.
Use the Took column of a green rehearsal to size the window. It counts the standard upgrade and your modules only, so allow for the backup, the copy and the restore on top.
With a promote, the instance's schedules and managed backup storage follow it, and every setting you changed on the prepared instance goes live with it. In place takes only what the table names.
Going back from an upgrade in place restores a whole instance, so In place needs a license that carries Clone, move and restore whole instances. On one that does not, How offers Promote only and says why, and the command line is refused the same way. Promote needs no restore: its way back moves the host names.
Running it
Choose How and press Upgrade production. A panel opens with This stops production for the length of the upgrade. Type the instance id it names, and press Upgrade production now.
When the way back fails too
A production upgrade that fails goes back by itself, as the table above says. Its outcome is RolledBack only when production runs again as it was. When the way back cannot finish, the run is Failed and What it said names the step that is left to you:
| The message says | What to do |
|---|---|
| it did NOT start again: start the instance by hand | Production was not changed. Start it from its page |
| The host names could NOT be moved back: make the instance production again by hand | After a promote. The old production's own database was not changed. Give it back its host names and Role, and start it |
| The way back FAILED too: restore the pinned backup on the instance by hand | After an upgrade in place. Restore the archive the message names, the pinned backup, into production from the command line, as below |
pelmo$ ohm instance restore --instance fanes --archive <the archive the message names>An ordinary restore like this one names the restored databases after the instance, where the automatic way back keeps their own names, so check the instance's database names and filters afterwards.
In each of these cases the pinned backup is kept on the backup volume, so it is there when you need it.
The old production
After a promote, the old production stays stopped, answers on a local name only, and has no Role. Its page shows Before upgrade: kept as the rollback. with the instance that took over.
It counts against the instance limit until you remove it by hand. Nothing removes it for you.
Rolling back
After a production upgrade that succeeded, the Roll back card appears on the tab of both
instances. Its button says what it takes back: Roll back the promote or Roll back the upgrade
in place. It shows a warning, and Roll back now carries it out. ohm instance upgrade rollback
does the same without asking.
- After a promote, the host names, certificate, backup settings and mail go back to the old production, which starts again on its own databases. The promoted instance goes back to being the prepared instance, with its Role back on Staging.
- After an upgrade in place, the pinned backup and the configuration saved in it are restored, and the instance starts on its old version. Every database comes back under its own name, so the addresses, database filters and integrations that name it keep working. If another database on the server has taken one of those names in the meantime, the rollback stops rather than write over it, and says so.
Everything written in the upgraded database after the upgrade stays behind: orders, invoices, mail, all of it. Nothing carries it back, and this cannot be undone. After a promote it stays in the prepared instance only until its next rehearsal, which starts from an empty instance. After an upgrade in place it is gone. Decide early, while there is little to lose.
A rollback needs what it goes back to. After a promote that is the old production: once it is removed, the Roll back card is gone and the upgrade is final. After an upgrade in place it is the pinned backup, which is removed with the prepared instance.
After the upgrade
Once production has been upgraded, nothing more runs on the plan: Rehearse, Re-run my modules and Upgrade production are done with it. When you are sure you will not go back:
- After a promote, remove the old production. That frees its place under the instance limit, ends the way back, and removes the upgrade's pinned backup and dumps from the backup volume. Until then the next upgrade cannot be prepared, because the old production is the rollback somebody may still need.
- After an upgrade in place, remove the prepared instance. That frees the disk, and ends the way back. It takes the plan, its rehearsal history, the stored dump and the pinned backup with it.
The next upgrade is then prepared as the first one was, on the Prepare upgrade card, which comes back when the plan has ended. After an upgrade in place it comes back at once: preparing the next upgrade replaces the plan, so its Roll back is gone, and the pinned backup stays on the backup volume until the old prepared instance is removed.
A failed production upgrade removes what it wrote to the backup volume, unless its way back failed too, when the pinned backup is what you need.
See Removing.
Limits by edition
Upgrading databases to a newer Odoo version comes with Professional and Provider only, for both
engines. Community, Developer and a server with no license upgrade nothing: Prepare upgrade,
Rehearse, Re-run my modules and Use as prepared instance are off and say why, the
Upgrade production card shows the reason instead of its button, and the command line is refused
the same way. ohm instance upgrade status prints the reason when the instance has no plan.
Roll back is never refused for lack of these features: an upgrade done while the license carried them can always be taken back.
Professional and Provider upgrade Community databases of any size. A license can carry a size limit of its own, per database, the database plus its filestore: the Prepare upgrade card then states it, and a larger database is refused when a run measures it, naming its size. Enterprise upgrades have no size limit.
Upgrades stay refused until the license carries these features, which arrive with the next license check-in after they are added to its plan. Check in now on the License page's License check-in card asks without waiting for the daily one.
A plan outlives a license that loses the feature: see When the license changes.
From the command line
ohm instance upgrade runs the same jobs, on the server or with --server, and a command that
queues a job follows it to the end with its log on the terminal:
| Command | What it does | Its options |
|---|---|---|
ohm instance upgrade prepare | Prepare upgrade | --target (required), --preset, and --fqdn for the names the prepared instance answers |
ohm instance upgrade rehearse | Rehearse | --copy-from, --max-age-days for the oldest local backup it may take, --confirm-odoo-transfer |
ohm instance upgrade rerun | Re-run my modules | |
ohm instance upgrade production | Upgrade production | --mode, --confirm-odoo-transfer |
ohm instance upgrade rollback | Roll back | |
ohm instance upgrade status | The plan, its runs, and whether production can move |
pelmo$ ohm instance upgrade prepare --instance fanes --target 18.0 --preset Testpelmo$ ohm instance upgrade rehearse --instance fanes --copy-from FreshBackuppelmo$ ohm instance upgrade status --instance fanespelmo$ ohm instance upgrade production --instance fanes --mode Promoteohm instance upgrade production and ohm instance upgrade rollback have no typed confirmation. The
production command stops production as soon as its checks pass.
--copy-from is FreshBackup or LatestLocalBackup, and --mode is Promote or InPlace, the
latter on a license that carries it. Setting custom-module branches and taking on a production on
another server are in the console only.