{"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":"python","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":[{"wrong":"from openupgradelib import openupgrade","symbol":"PackageNotFoundError","correct":"from openupgradelib import PackageNotFoundError"},{"wrong":"from openupgradelib import openupgrade","symbol":"version","correct":"from openupgradelib import version"}],"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,"search_vec":"'activ':56 'address':72 'aim':36 'associ':31 'call':17 'challeng':76 'common':73 'communiti':30,47 'compat':64 'compon':26 'data':74 'databas':82 'design':14 'edit':48 'ensur':63 'erp':81 'function':12 'fundament':25 'instanc':49 'latest':67 'librari':3,9,54 'maintain':57 'major':51 'migrat':20,75,78 'new':59 'oca':32,80 'odoo':1,19,29,46,68,77 'offer':38 'open':41 'open-sourc':40 'openupgrad':2,33 'openupgradelib':5 'path':44 'period':61 'project':34 'provid':10 'python':8 'releas':58 'script':21 'sourc':42 'specif':13 'support':11 'upgrad':43,79 'version':52,60,69","created_at":"2026-04-16T17:01:53.973061+00:00","updated_at":"2026-04-16T17:01:53.973061+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.13.2","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/OCA/openupgradelib","docs":null,"changelog":null,"pypi":"https://pypi.org/project/openupgradelib/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","devops","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":null}}