Odoo 模块安装错误版本不匹配 — 修复指南

You try to install or upgrade a custom Odoo module and the operation fails with:

ERROR: incompatible module 'sale_extension': declared version '18.0.1.0.0',
       server version '17.0'

Or the variant:

ERROR: cannot install module 'mrp_workorder_priority': dependency 'mrp_subcontracting'
       not satisfied (required >= 17.0.2.0.0, installed 17.0.1.0.0)

This is Odoo's manifest validator doing exactly what it should. The fix is mechanical, but understanding which of the four version mechanisms is biting you is the speed-up. Applies to Odoo 17.0/18.0/19.0.

Quick Fix

Open __manifest__.py and align the version with the server's major version. The first two numbers must match the Odoo major version exactly:

# WRONG — for an Odoo 17 server
'version': '18.0.1.0.0',

# RIGHT — for an Odoo 17 server
'version': '17.0.1.0.0',

After fixing, restart Odoo and re-install. If the dependency variant is firing, bump or relax the version constraint:

'depends': ['mrp', 'mrp_subcontracting'],   # do not pin to a specific patch

Why This Happens

Odoo modules carry a four-or-five-segment version: 17.0.1.0.0 means Odoo major 17.0, module version 1.0.0. The validator checks:

1. Server-major match. The first two segments must equal the server's major (17.0, 18.0, 19.0). A mismatch here aborts installation.
2. Manifest version vs database version. If ir_module_module.latest_version is newer than __manifest__.version, Odoo refuses to "downgrade" a module silently.
3. Dependency version constraints. Modules can declare depends with version pins; if the installed dependency is older than required, install fails.
4. Code-vs-manifest drift. You bumped the code but forgot to bump the manifest. Odoo skips your migrations because the version did not change.

The four common scenarios:

• Copying a module from a newer Odoo branch (a 19.0 module copied into a 17.0 instance). The version prefix is wrong.
• Pulling main of an OCA repo without checking out the version branch. OCA branches are version-named (17.0, 18.0, 19.0). Main does not exist; the version branch is the truth.
• Upgrading after a partial deploy where the new code is on disk but the manifest was not bumped, so Odoo thinks nothing changed.
• Mixing Enterprise and Community module versions (Enterprise 18.0.4 dependency required by a Community 18.0.0 baseline).

Step-by-Step Diagnosis

1. Check the server's major version.

sudo -u odoo /opt/odoo/odoo-bin --version
# Odoo Server 17.0

2. Check the failing module's manifest:

grep "'version'" /opt/odoo/addons/sale_extension/__manifest__.py
# 'version': '18.0.1.0.0',  <-- mismatch

3. Check installed dependencies:

SELECT name, latest_version, state
FROM   ir_module_module
WHERE  name IN ('mrp', 'mrp_subcontracting', 'sale_extension')
ORDER  BY name;

Compare each latest_version to what your failing module's depends requires.

4. Look for code-vs-manifest drift.

git log -1 --pretty=format:"%h %s" -- /opt/odoo/addons/sale_extension/
git log -1 --pretty=format:"%h %s" -- /opt/odoo/addons/sale_extension/__manifest__.py

If the source has newer commits than the manifest, the manifest needs a version bump.

5. Check addons_path for duplicates.

sudo -u odoo /opt/odoo/odoo-bin --config /etc/odoo/odoo.conf --print-config | grep addons_path
find / -name "sale_extension" -type d 2>/dev/null | grep -v __pycache__

If the module exists in two places under addons_path, Odoo loads the first match. A stale copy hides the corrected one.

Permanent Fix

For server-major mismatch, set the manifest correctly and re-install:

# __manifest__.py for an Odoo 17 server
{
    'name': 'Sale Extension',
    'version': '17.0.1.0.0',  # major.minor must match server
    'depends': ['sale'],
    'license': 'LGPL-3',
    ...
}

If you need this module on multiple Odoo versions, maintain a branch per version. Do not branch by feature within the version dimension.

For dependency version mismatches, decide whether to relax the constraint or upgrade the dependency:

# Relax if your code does not actually need the new version's behaviour:
'depends': ['mrp_subcontracting'],

# Or upgrade the dependency:
# pip install --upgrade <package>  # if it is a Python dep
# git pull && -u mrp_subcontracting  # if it is an Odoo module

For code-vs-manifest drift, bump the manifest version on every meaningful change:

# Was: 'version': '17.0.1.0.0'
# Now: 'version': '17.0.1.1.0'  # bump after any data model change

Use semver for the last three segments: major.minor.patch within the Odoo version line. Bump patch for bug fixes, minor for new features, major for breaking changes.

For duplicate modules in addons_path, fix addons_path order in odoo.conf and remove the stale copies:

# odoo.conf — explicit, ordered, no globs
addons_path = /opt/odoo/addons,/opt/odoo/enterprise,/opt/odoo/custom_addons

Ensure custom_addons is listed once, and the corrected module lives there.

How to Prevent It

• CI gate on manifest version. Add a CI check that fails the build if any module's manifest major-minor does not match the target Odoo branch. This catches "copied from main" mistakes pre-merge.
• Always check out the version branch on OCA. git checkout 17.0 before pulling. OCA repos do not have a single main branch.
• Bump version on every commit that touches data. Make it a commit-message convention. Tooling can enforce it (commitlint rules + a Python check).
• One manifest, one version. Do not maintain a version_compat.py or a parameter file. The manifest is the single source of truth.
• Test installation on a fresh database. As part of CI, install your module on a fresh database every release. Catches missing dependencies and version mismatches before they hit production.
• Document target Odoo version in the module README. A 30-second read for the next developer saves hours of debugging.

Related Errors

• Upgrade aborted, database corrupted — what happens when a partial install gets retried.
• Module not loadable with traceback — different failure mode in the same install pipeline.
• Mismatched server vs modules version — sibling check, runs at a different stage.
• Data not found during init — what you see after a successful version match but the data file is missing.

Frequently Asked Questions

Can I install a 17.0 module on an 18.0 server?

Sometimes yes, sometimes no. The version check itself fails, but if you are confident the module's API usage is forward-compatible, you can manually edit the manifest and try. Most of the time, fields, methods, or view shapes have moved between versions and the install or migrate step blows up later. Migration via openupgrade is the right path.

What does each segment of the version mean?

<odoo_major>.<odoo_minor>.<module_major>.<module_minor>.<module_patch>. So 17.0.2.1.3 is Odoo 17.0, module version 2.1.3. The first two segments are the Odoo version (the minor is always 0 for Enterprise/Community releases). The last three are your semantic version.

Why does the dependency constraint look at latest_version instead of the module's installed version?

Because Odoo modules update in place — there is no notion of "version 1 and version 2 installed side by side". latest_version is what the database currently has, which is also what the live module is. The constraint checks "is the live one new enough".

My module installs fine but does not appear in the Apps list. What is wrong?

Either the module is in a path Odoo did not load (check addons_path and restart), or the manifest is missing required keys (name, version, depends are all mandatory), or installable: False is set in the manifest. Check installable first — it is the most common silent hide.

---

Need help with a tricky Odoo error? ECOSIRE's Odoo experts have shipped 215+ modules — get expert help.