← Back to Blog
Technical Insights by

Why We Add Bundle Modules to Your Codebase Before Migrating Odoo

Why We Add Bundle Modules to Your Codebase Before Migrating Odoo

When we start a migration, one of the first things we ask is unusual: before touching the new version, we add two small modules to your current codebase, deploy them to production, and install them. Your users will not see anything. No new menu, no new field, no change in how they work.

You may reasonably ask why. Your database has run for years without these modules, and a migration should be about the new version, not about adding things to the old one. This post explains why we do it, from the point of view of the team that runs the migration.

TL;DR

  • A bundle module is a list of modules, packaged as a module. It has no features of its own. Its only content is the list of modules your project needs.
  • A migration needs a place for project-wide fixes. Odoo runs migration scripts per module. Fixes that belong to no single module, such as cleaning up old data or taking out modules we do not migrate, need a module to live in. The bundle is that module.
  • It must be installed before the upgrade starts. The upgrade starts from a copy of your production database, and Odoo only runs scripts for modules that are already installed. That is why we deploy it on your current version first.
  • After the migration, it keeps your environments consistent. One list says what your project installs, so a test environment or a restore gets the same modules as production, and new modules arrive through a commit instead of being installed manually from the Apps menu.

What a Bundle Module Is

Every Odoo project uses three kinds of modules: Odoo’s own, community modules (most of them from the Odoo Community Association, OCA), and modules written for the project. Over the years, the answer to “which modules does this project need?” ends up spread across the database, the code and people’s memory.

A bundle module writes that answer down in one place. It is an almost empty module whose manifest lists every module the project needs as a dependency:

{
    "name": "Your Project Bundle",
    "depends": [
        "sale_management",
        "stock",
        "auditlog",          # OCA
        "your_custom_sales", # written for your project
        # ...
    ],
}

Installing the bundle installs everything it lists, in the right order, because Odoo resolves the dependencies itself.

We usually add two bundles, not one:

  • <project>_bundle for Odoo Community and community modules;
  • <project>_bundle_ee for Odoo Enterprise modules.

The split follows licensing. Most OCA modules are published under the AGPL, Odoo Enterprise under its own proprietary licence, and keeping the two lists apart keeps each module’s licence obligations clear. If you do not use Enterprise, there is only one bundle.

Why the Migration Needs It

A home for the fixes that belong to no single module

Moving from one Odoo version to another is done by Odoo’s upgrade service for Odoo’s own modules, and by us for the rest. Odoo lets every module carry migration scripts, which run when that module is upgraded: before it is loaded, after it is loaded, or at the very end.

Most of our scripts belong to a specific module. But every migration also has fixes that do not, for example:

  • Old data that the new version refuses. A date typed as year 0023 instead of 2023, a leave allocation of zero days, a record missing a field that has become required. The new version adds rules the old one did not have, and the upgrade stops if existing data breaks them.
  • Modules we decided not to migrate. A module that is not ported is still marked as installed in your database, and its screens still extend Odoo’s. Something has to switch them off and mark them as uninstalled, or they will break the new version’s screens.
  • Leftovers. Messages pointing to records that the new version removed, asset definitions from the old interface, and similar clean-up.

None of these belongs to one of your modules. Without a project module, they would end up scattered across unrelated modules, or run by hand outside the upgrade, where they are not repeated on each test and are easy to forget on the day of the real migration. In the bundle, they are part of the code, reviewed, and run automatically on every test upgrade and on the final one.

One limit is worth knowing: the bundle depends on almost everything, so Odoo upgrades it last, after the modules its fixes are about. That suits fixes that only need to run once everything else is upgraded, such as cleaning up leftovers. It does not suit fixes that must happen before a module is upgraded, because by the time the bundle runs, that module has already been upgraded.

An example makes this clearer. Say the new version of one of your modules requires every delivery to have a carrier, and some old deliveries have none:

  1. Odoo upgrades that module first, and tries to apply the new rule to your existing deliveries.
  2. The old deliveries without a carrier break the rule, so the problem appears during that module’s upgrade.
  3. The bundle only runs afterwards, too late to fill in the missing carriers.

The missing carriers therefore have to be filled in before that module is upgraded: either as a correction on your current version before the upgrade, or in a script that runs at the very start of the upgrade. Choosing the right place for each fix is part of our work.

Why it has to be installed on the old version first

This is the part that surprises people most, so it deserves a precise answer.

An upgrade does not start from an empty database. It starts from a copy of your production database, which Odoo’s service upgrades, and then your modules are upgraded on top of it. Odoo only runs migration scripts for modules that are installed in that database. A module that appears for the first time in the new version is not upgraded: at best it is installed, and an install does not run migration scripts.

So if the bundle only existed in the new version, the fixes above would never run. It has to be in the database before the copy is taken, which means:

  1. we add the bundle to your current codebase, listing only modules that are already installed;
  2. we deploy it to production, on your current version, and install it;
  3. from then on, every test upgrade, and the final one, starts from a database where the bundle is installed.

Installing it on the old version is quick and changes nothing for your users: everything it lists is already installed, so Odoo has nothing new to install. In practice, it is one small deploy, best done early in the project, so that the first test upgrade already uses it.

A cleaner way to migrate step by step

The bundle also helps us during the test phase. While modules are being ported one by one, the bundle’s scripts can keep the ones that are not ready out of the test database. You get a working test environment on the new version early, with Odoo’s standard features and whatever is already ported, instead of waiting until every module is done. Each module joins the next test upgrade when it is ready.

What It Gives You After the Migration

The bundle does not disappear once the migration is done, and we recommend keeping it:

  • Every environment gets the same modules. A new test database, a training copy or a restore after an incident is built from the same list as production. Nothing depends on someone remembering which modules were installed by hand.
  • New modules arrive through a commit. Adding a module to your project means adding it to the bundle’s list, through the same review and testing as any other change. It is installed automatically at the next deploy, instead of from the Apps menu on the live database, where an install can slow down or block users while it runs, and where a module nobody has tested can have side effects.
  • The next migration starts with the work already done. The bundle is in place, and the list of modules is up to date.

What It Means for You

  • For your users: nothing visible. No menu, no field, no data they would see.
  • For your codebase: one or two small modules, reviewed like any other code we deliver.
  • For the planning: one deploy on your current version, early in the project, before the first test upgrade.

Questions We Usually Get

Can’t you put the scripts in one of our existing modules?

For fixes that clearly belong to one of your modules, we do. For the others, putting them in an unrelated module makes them hard to find, ties them to that module’s dependencies and upgrade order, and makes the next developer wonder why a sales module is cleaning up leave allocations.

Can we remove the bundle after the migration?

You can, but we would advise against it. It costs nothing to keep, and removing it means losing the single list of what your project installs, and redoing this step at the next migration.

Does it change anything for licences?

No. The bundles only list modules you already use. Keeping Community and Enterprise modules in separate bundles is precisely about keeping each licence clear.

What if a module in the list is no longer used?

That is part of the scoping we do with you at the start of the migration. Modules we agree not to migrate are taken out by the bundle’s scripts, and they no longer appear in the list for the new version.

Can we still install a module from the Apps menu?

Odoo still lets an administrator do it, but we advise against it on production. A module installed that way is not in the bundle’s list, so it is missing from every test environment, every restore and the next migration, and nobody has tested it with the rest of your modules. The install itself also runs on the live database and can slow down or block your users while it runs. If you need a new module, tell us: we add it to the bundle, test it on a copy of your database, and it is installed at the next deploy. If one has to be installed in an emergency, let us know afterwards so we can add it to the list.