{"id":8383,"library":"openupgradelib","title":"Odoo OpenUpgrade Library","description":"The `openupgradelib` is a Python library providing support functions specifically designed to be called from Odoo migration scripts. It is a fundamental component of the Odoo Community Association (OCA) OpenUpgrade project, which aims to offer an open-source upgrade path for Odoo Community Edition instances between major versions. The library is actively maintained, releasing new versions periodically to ensure compatibility with the latest Odoo versions and to address common data migration challenges.","status":"active","version":"3.12.0","language":"en","source_language":"en","source_url":"https://github.com/OCA/openupgradelib","tags":["Odoo","migration","upgrade","OCA","ERP","database"],"install":[{"cmd":"pip install openupgradelib","lang":"bash","label":"Stable release"},{"cmd":"pip install git+https://github.com/OCA/openupgradelib.git@master#egg=openupgradelib","lang":"bash","label":"Latest development version (recommended for migrations)"}],"dependencies":[{"reason":"This 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).","package":"Odoo","optional":false}],"imports":[{"note":"The primary API is exposed through the `openupgrade` module directly under `openupgradelib`. Older or internal modules like `openupgrade_tools` should not be imported directly.","wrong":"from openupgradelib.openupgrade_tools import ...","symbol":"openupgrade","correct":"from openupgradelib import openupgrade"}],"quickstart":{"code":"import logging\nfrom openupgradelib import openupgrade\n\n_logger = logging.getLogger(__name__)\n\n@openupgrade.migrate()\ndef migrate(env, version):\n    _logger.info(\"Starting migration script for version %s\", version)\n\n    # Example 1: Execute a raw SQL query with logging\n    openupgrade.logged_query(\n        env.cr,\n        \"UPDATE res_users SET company_id = 1 WHERE company_id IS NULL\",\n        \"Setting default company for users without one\"\n    )\n\n    # Example 2: Add a new column to an existing model\n    # This is typically done in a 'pre-migrate' script to prepare the database schema\n    openupgrade.add_columns(\n        env,\n        [\n            ('res.partner', 'x_migrated_status', 'char', None, 'res_partner', 'varchar(64)', False),\n        ]\n    )\n\n    # Note: After adding columns or fields, Odoo's ORM cache often needs to be cleared or re-initialized\n    # For schema changes, _auto_init() or _fields.clear() might be needed for ORM awareness in later steps.\n    # env['res.partner']._fields.clear()\n    # env.cr.commit() # Commit changes if needed before further ORM operations\n\n    _logger.info(\"Migration script completed.\")","lang":"python","description":"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."},"warnings":[{"fix":"Remove the `norecompute` argument when calling `openupgrade.merge_records`. Review the logic to ensure computed fields are handled correctly post-merge.","message":"The `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.","severity":"deprecated","affected_versions":">=3.11.0 (openupgradelib), >=17.0 (Odoo)"},{"fix":"Ensure 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).","message":"Direct 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.","severity":"breaking","affected_versions":">=2.0.0 (openupgradelib), Odoo <=9.0"},{"fix":"Add `\"openupgradelib\"` to the `python` list in the `external_dependencies` dictionary within your `__manifest__.py`:\n`'external_dependencies': {'python': ['openupgradelib']},`","message":"When 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Plan 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.","message":"The 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `openupgradelib` is correctly installed via pip in the Odoo environment. For complex setups or older Odoo versions, verify that the `OpenUpgrade` framework (which uses `openupgradelib`) and `openupgradelib` itself are compatible versions and accessible on the Python path. Using `pip install git+https://github.com/OCA/openupgradelib.git@master#egg=openupgradelib` for the library and cloning the corresponding OpenUpgrade branch for migration scripts often resolves such issues.","cause":"This error often occurs in older Odoo migration setups (e.g., Odoo 7.0/8.0) when `openupgradelib` or `OpenUpgrade` migration scripts are incorrectly installed or their versions are mismatched.","error":"ImportError: No module named openupgradelib.openupgrade_tools"},{"fix":"Ensure that the `openupgradelib` installed matches the version expected by the `OpenUpgrade` migration scripts you are using. It's often recommended to install `openupgradelib` directly from the `master` branch of its GitHub repository using `pip install git+https://github.com/OCA/openupgradelib.git@master#egg=openupgradelib` to ensure the latest compatible version.","cause":"This error typically arises when the installed `openupgradelib` version is out of sync with the `OpenUpgrade` (migration scripts) codebase, specifically when a newer `OpenUpgrade` expects a `migrate` function signature that the installed `openupgradelib` version doesn't support.","error":"TypeError: migrate() got an unexpected keyword argument 'use_env'"},{"fix":"Upgrade `openupgradelib` to version 3.13 or newer, which includes a fix for this issue (commit OCA/openupgradelib#410). This version correctly accesses the module name from the `addon` parameter.","cause":"In `openupgradelib` versions prior to 3.13, the library attempted to retrieve the module name from `frame.locals['pkg'].name`. Recent changes in Odoo's core (specifically related to how upgrade scripts are run and arguments are passed) caused the `'pkg'` key to become unavailable.","error":"KeyError: 'pkg' (or similar error when accessing module name in migration)"}]}