Install & Compatibility
Where this runs
tested against v3.13.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PackageNotFoundError
✓ from openupgradelib import PackageNotFoundError
✗ from openupgradelib import openupgrade
version
✓ from openupgradelib import version
✗ from openupgradelib import openupgrade
To use `openupgradelib`, create a Python file within your Odoo module's `migrations/<ODOO_VERSION>/` directory (e.g., `my_module/migrations/16.0.1.0/pre-migrate.py`). Decorate your `migrate` function with `@openupgrade.migrate()` to ensure it runs correctly within the OpenUpgrade framework, providing access to the `env` (Odoo environment) and `version` (migration version) objects. This example demonstrates running a logged SQL query and adding a new column, two common migration tasks.
import logging
from openupgradelib import openupgrade
_logger = logging.getLogger(__name__)
@openupgrade.migrate()
def migrate(env, version):
_logger.info("Starting migration script for version %s", version)
# Example 1: Execute a raw SQL query with logging
openupgrade.logged_query(
env.cr,
"UPDATE res_users SET company_id = 1 WHERE company_id IS NULL",
"Setting default company for users without one"
)
# Example 2: Add a new column to an existing model
# This is typically done in a 'pre-migrate' script to prepare the database schema
openupgrade.add_columns(
env,
[
('res.partner', 'x_migrated_status', 'char', None, 'res_partner', 'varchar(64)', False),
]
)
# Note: After adding columns or fields, Odoo's ORM cache often needs to be cleared or re-initialized
# For schema changes, _auto_init() or _fields.clear() might be needed for ORM awareness in later steps.
# env['res.partner']._fields.clear()
# env.cr.commit() # Commit changes if needed before further ORM operations
_logger.info("Migration script completed.")
Debug
Known issues
deprecatedThe `norecompute` argument for `merge_records` was deprecated in Odoo v17 and removed from `openupgradelib` version 3.11.0. Using it will lead to errors in newer Odoo versions.fixRemove the `norecompute` argument when calling `openupgrade.merge_records`. Review the logic to ensure computed fields are handled correctly post-merge.
affects: >=3.11.0 (openupgradelib), >=17.0 (Odoo)
breakingDirect Python 2 support has been dropped. Installing `openupgradelib` (especially recent versions) in an Odoo environment running Python 2 will result in `SyntaxError` or other compatibility issues.fixEnsure your Odoo instance is running on Python 3 when using recent `openupgradelib` versions. If migrating older Odoo versions that require Python 2, use an older `openupgradelib` version known to be compatible (e.g., <=1.x.x).
affects: >=2.0.0 (openupgradelib), Odoo <=9.0
gotchaWhen developing custom Odoo modules that utilize `openupgradelib` for their own migrations, it is crucial to declare `openupgradelib` in the `external_dependencies` section of your Odoo module's `__manifest__.py` file. Failure to do so can lead to `ModuleNotFoundError` in environments that auto-install Python dependencies based on Odoo manifests.fixAdd `"openupgradelib"` to the `python` list in the `external_dependencies` dictionary within your `__manifest__.py`:
`'external_dependencies': {'python': ['openupgradelib']},` affects: All
gotchaThe OpenUpgrade project, and thus `openupgradelib`, is designed for sequential major version upgrades (e.g., Odoo 15.0 to 16.0, then 16.0 to 17.0). Skipping intermediate major Odoo versions (e.g., directly from 15.0 to 17.0) is not officially supported and will likely result in data inconsistencies or migration failures.fixPlan your Odoo migrations as a series of sequential upgrades, migrating one major version at a time, ensuring each step completes successfully before proceeding to the next.
affects: All
Upgrade
Version history
3.13.2latest on PyPI · released Jun 2, 2026
Audit
Dependencies
OdoorequiredThis library is a helper for Odoo database migrations and is typically used within an Odoo environment. It expects to interact with an Odoo `env` object or `cr` (cursor).