Custom Odoo Module Migration
Migrating a custom Odoo module from one major version to another without breaking functionality requires a clear plan across audit, code changes, data, and testing phases.
The problem
Custom modules often rely on APIs and patterns that change between Odoo versions. Moving a module to a new major release means reconciling differences in the manifest, models, views, security files, and JavaScript before the module will install and run.
Why it matters
Failing to identify breaking changes leads to runtime errors, data corruption, and broken views. A module that installed cleanly on the source version can fail at upgrade time, leaving records inaccessible or actions unusable in production.
Common symptoms
- Module fails to install on the target version
- Views do not render or raise parse errors
- JavaScript errors appear in the browser console
- Fields are missing in the database after upgrade
- Access rights break and records become unreachable
Example risk
A field modifier written with attrs works on Odoo 15 but is deprecated from Odoo 16 onward and requires Python-side visibility control instead.
<field name="partner_id"
attrs="{'invisible': [('state', '!=', 'draft')]}"/>On Odoo 16+ the same intent is expressed with a direct attribute bound to a field value:
<field name="partner_id"
invisible="state != 'draft'"/>How to audit it
- Run a Migration Audit selecting the source and target versions.
- Review XML for deprecated attributes and fragile
xpathselectors. - Check JavaScript for
odoo.definepatterns. - Verify field references and
ir.model.access.csvagainst the target version.
How Odoo Doctor helps
The Migration Audit tool scans your module ZIP and identifies specific risks with remediation guidance, mapping each finding to a file and line so you know exactly where to look.
Manual testing needed
Run the module in a clean target database. Test all views, workflows, computed fields, server actions (ir.actions.server), and access rights manually before promoting to production.
Plan your migration with confidence
Scan your module and review a prioritized list of migration risks.
Run Migration AuditFrequently asked questions
Can Odoo Doctor migrate my module automatically?
No. The Migration Audit performs static analysis and flags risks with file and line references. You apply code changes and test them yourself in a clean target database.
Should I migrate one major version at a time?
For large gaps it is usually safer to step through intermediate versions, since breaking changes accumulate. Review each version's removals to __manifest__.py dependencies, fields, and view attributes before jumping ahead.
What parts of a module break most often during migration?
XML view inheritance (XPath selectors), deprecated attrs/states attributes, legacy odoo.define JavaScript, ir.model.access.csv format, and field references that no longer exist in the target version.
Do I still need manual testing after an audit?
Yes. Static analysis cannot observe runtime behavior. Install the module in a clean target database and test views, workflows, computed fields, server actions, and record rules.