OCA OpenUpgrade is a versioned migration layer for Odoo databases

A migration layer that lives next to the version it targets

OpenUpgrade is the Odoo Community Association repository for upgrading Odoo, formerly OpenERP, installations. The important structural detail is how the project is versioned. The default branch is `19.0`, and the addon versions inside it carry the same prefix, `19.0.1.0.0` for both modules, so the branch and the release series of Odoo are the same axis. The pattern that follows from that is the standard one for this kind of project: each Odoo major version gets its own branch, and the migration code for that specific transition lives on it. The audience is self hosted operators and integrators who control their own upgrade schedule. People on the hosted commercial offering or on a managed platform are not the target, since there is no indication here of any hosted service. What the repository is, in one sentence, is the collected analysis of what changed between two Odoo versions plus the scripts that act on those changes.

Two addons: a framework and a bag of scripts

The repository ships two addons, and the split between them is the thing to understand before reading any of the code. The project lists them in a table of available addons.

addon | version | maintainers | summary
--- | --- | --- | ---
[openupgrade_scripts](openupgrade_scripts/) | 19.0.1.0.0 |  | Module that contains all the migrations analysis and scripts for migrate Odoo SA modules.

The scripts addon is the payload, holding the migration analysis and the scripts that migrate the Odoo standard modules. The other addon, `openupgrade_framework`, is described as a module to integrate in the `server_wide_modules` option to make upgrades between two major revisions. So one addon is content, specific to a version pair, and the other is the mechanism that runs the content inside the Odoo server process. The maintainers column is populated for the framework addon and empty for the scripts addon, which reflects the shape of the split: the framework is a shared library that needs owning, and the scripts are version specific churn.

server_wide_modules is the hook that starts an upgrade

The documented integration point is a single Odoo server option. The framework addon has to be integrated in the `server_wide_modules` option, and that is what makes upgrades between two major revisions possible. This is worth dwelling on, because it determines the deployment order of an upgrade. The framework is not something a user invokes from inside an Odoo screen; it is loaded by the server at startup because it is registered as a server wide module, and from there it can take part in the upgrade run. For an operator, the practical consequences are that a new addon has to be installed in the target version's addons path before the upgrade starts, and that the server configuration has to be changed before the process that performs the migration is launched. Anyone looking for a documented command line procedure here will not find one in the repository documentation, and the tooling in the repository is aimed at developers working on the migration code rather than at end users running an upgrade.

A requirements file generated from the addon manifests

The dependency list is short and it is machine generated, which is a detail about how the repository is maintained. The `requirements.txt` at the root contains a single comment and a single package.

# generated from manifests external_dependencies
openupgradelib

The comment says the file is generated from the manifests' `external_dependencies`, so the dependency set is derived from the addons themselves rather than maintained by hand. The practical dependency for a deployment is therefore `openupgradelib`, and any other module that declares its own external dependencies would add itself in the same way. This is a different shape from a normal Python project, where a single hand written requirements file governs the environment. Here the environment is mostly supplied by the Odoo instance, and this file only records what the addons need on top of it. It also means a change in a manifest can change the requirements file, so the file should not be edited directly.

Per module licences sit underneath an AGPL repository

The licensing is layered, and the layering is stated explicitly. The repository itself is licensed under AGPL-3.0, and the project points to the `LICENSE` file for that. However, the documentation goes on to say that each module can have a totally different licence, as long as they adhere to Odoo Community Association policy, and it instructs readers to consult each module's `__manifest__.py` file, which contains a `license` key that explains its licence. For an adopter, the practical rule is that the repository licence is the fallback, not the answer for a specific addon, and that the manifest of each module is the file to read. The wider context is organisational as well as legal. OCA is described as a nonprofit organisation whose mission is to support the collaborative development of Odoo features and to promote their widespread use, and the modules here are covered by OCA policy rather than by a single blanket decision. The AGPL-3.0 grant at the repository level is the part to plan for if you modify and deploy the code.

Linting, formatting and a repository generated from a template

The engineering setup around the addons is visible in the repository root, and it tells you what a contribution has to satisfy. There is a `.pre-commit-config.yaml`, so checks run before a commit is created. There is a `.ruff.toml` for the Python linter and formatter, two pylint configuration files, `.pylintrc` and `.pylintrc-mandatory`, for a lint pass whose results are split into two severity tiers. There are `eslint.config.cjs` and `prettier.config.cjs` with a `.prettierignore` for the non Python assets, and an `.editorconfig` and `.gitattributes` for line endings and file handling. A `.copier-answers.yml` shows the repository is itself produced from a template, and `checklog-odoo.cfg` holds configuration for a check log. Documentation sources live in `docsource/`, and there is a `setup/` directory. The pre-commit and CI badges in the project header point at a pre-commit workflow and a test workflow, and codecov and a translation service are wired in for the branch. For a contributor this is a well instrumented repository, and for a user it is a signal that the migration code is reviewed and tested rather than ad hoc.

Where this repository stops and your own code begins

The boundary of the project is stated in the addon summary rather than in fine print. The scripts addon contains the migrations analysis and scripts for migrating Odoo standard modules, and the repository as a whole is described as an open source upgrade path for Odoo and OpenERP. Nothing in the repository addresses custom addons written by a customer or an integrator, and nothing here analyses your own data model. That is the most common reason an upgrade stalls in practice: the standard modules are covered, and the business modules that sit on top of them are not, so somebody has to write those migration steps by hand for the customer. The other limitation is visible in the release history. The only listed release is a `databases` entry, described as test databases, dated 2017-10-03, so the published release tags are not where the work is tracked, even though the last push to the branch was on 2026-10-19. Day to day movement happens in commits on the branch, and the practical way to see what changed for a given transition is to read the diff between the two version branches.

An addon framework versus hand written migration scripts

There is a second way to run an Odoo upgrade, and it is worth choosing deliberately. The approach used here is an addon framework plus a library of per version scripts, where the framework is registered in `server_wide_modules` so the server itself carries the migration machinery, and the scripts are content that changes with every release. The alternative is to drive the migration from outside, with a script written by the integrator that uses `openupgradelib` directly, with no addon installed in the Odoo instance. The difference in approach is about ownership and blast radius. The framework route gives a shared, version tested set of scripts for the standard modules and puts the upgrade inside a process that already knows how to manage the database, but it requires changing the server configuration and installing an addon in the target version. The external script route leaves the Odoo installation untouched and lets the integrator control the order of operations, but every environment, every customer and every version pair needs its own maintenance. For a standard community installation, the addon route is the one that scales across customers; for a single bespoke instance with unusual steps, a local script can be simpler.

Editorial conclusion

Adopt OpenUpgrade if you run Odoo Community or OpenERP and need to move a database across a major version, and if you can add the framework addon to the `server_wide_modules` option of your Odoo instance. Skip it if the upgrade is between minor releases inside one major line, or if your blockers are in custom addons you maintain yourself, since this repository covers the Odoo standard modules. Verify three things first: that the branch you are reading matches the Odoo version you are upgrading to, that the `openupgrade_framework` addon is installed in the server wide modules list before the upgrade runs, and that the `license` key in each `__manifest__.py` file says what you expect, because the repository licence and the module licences are not the same thing.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. OCA/OpenUpgrade on GitHub
3. Project website
4. README
5. Releases