Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 39 ยท Modules and Business Apps

Module Lifecycle: Install, Update, Uninstall and Hooks

Learn what happens when an Odoo module is installed, updated and removed, and use init and uninstall hooks plus migration scripts safely.

A module is not only code that runs; it is something you install, change over many releases and eventually remove from live databases that contain real data. Odoo gives you a clear lifecycle for this: install, update (upgrade), uninstall, and hook points where your own Python can run. This lesson explains each stage and the rules that keep customer data safe.

The states of a module

A module row in ir_module_module has a state:

State Meaning
uninstalled Found in addons path but not installed
to install Marked for installation at the next server cycle
installed Loaded on every start
to upgrade Will be updated at the next cycle
to remove Will be uninstalled

Pressing a button in the Apps menu changes the state and reloads the registry. From the command line, -i, -u and the options --stop-after-init do the same without the interface.

Install

On install, Odoo runs these steps in order:

  1. Installs missing dependencies first.
  2. Runs the pre-init hook if the manifest declares one.
  3. Imports the Python code and creates or alters tables for the module's models.
  4. Loads the data files, then the demo files if demo data is on.
  5. Loads translations.
  6. Runs the post-init hook.
  7. Marks the module as installed.

Update

Updating (-u my_module or the Upgrade button) is not a reinstall. Odoo re-imports the Python code, adds new columns for new fields, re-reads all data files, applies updates by external id and runs migration scripts for the new version number. What it does not do:

  • It does not delete columns of fields you removed from Python (the old data stays in the table).
  • It does not delete records whose XML you removed, unless you use <delete>, or the record is noupdate and unchanged (cleaned up under specific rules; do not rely on it).
  • It does not change the type of an existing column silently in risky ways; changing a field's type often needs a migration script.

Hooks

Hooks are Python functions in the module's top-level __init__.py, named in the manifest. Odoo calls them with an environment object:

Python
# my_module/__init__.py
from . import models


def pre_init_hook(env):
    """Runs before the module's tables are created."""


def post_init_hook(env):
    """Runs after install: one-time setup that XML cannot express."""
    partners = env["res.partner"].search([("customer_rank", ">", 0)])
    partners.write({"loyalty_level": "bronze"})


def uninstall_hook(env):
    """Runs when the module is removed: clean up what you created."""
Python
# my_module/__manifest__.py
{
    "name": "Loyalty",
    "depends": ["base"],
    "pre_init_hook": "pre_init_hook",
    "post_init_hook": "post_init_hook",
    "uninstall_hook": "uninstall_hook",
}

Hook signatures differ between series: older versions pass (cr, registry) instead of env. Match the signature of the series you target.

Use post_init_hook for one-time data conversion on existing records. Use pre_init_hook when you must prepare the database before the ORM creates something, for example to add a column with a default on a huge table quickly.

Migration scripts

When you release version 1.1.0 and change the data structure, ship a migration script in a migrations folder. Odoo runs scripts whose version is newer than the installed version during the update:

TEXT
my_module/
โ””โ”€โ”€ migrations/
    โ””โ”€โ”€ 18.0.1.1.0/
        โ”œโ”€โ”€ pre-migrate.py
        โ””โ”€โ”€ post-migrate.py
Python
# migrations/18.0.1.1.0/pre-migrate.py
def migrate(cr, version):
    cr.execute("ALTER TABLE vet_pet RENAME COLUMN weight TO weight_kg")

A pre- script runs before the new code is loaded (good for renaming a column, so the ORM does not create a second empty column), a post- script runs afterwards (good for filling new fields). Remember to raise the version in the manifest, because the version number triggers the scripts.

Uninstall

Uninstalling a module deletes what it created through XML: records with external ids owned by the module (views, menus, actions), and its model and field metadata. Models defined only by that module have their tables dropped, with the data in them; columns that the module added to other models are dropped as well. This is why uninstalling a module that stores business data is a serious step: back up first. The uninstall_hook is the place to remove side effects Odoo cannot know about, such as files or records in unrelated tables.

stateDiagram-v2
    [*] --> uninstalled
    uninstalled --> installed: install (hooks, data)
    installed --> installed: update (migrations)
    installed --> uninstalled: uninstall (hook, data removal)

A module can be updated many times between install and uninstall.

A runnable stand-in: versioned migrations

The mechanics of "run every migration newer than the installed version" are easy to simulate. This stand-in keeps a fake table and applies scripts in version order, printing what ran.

Python Stand-in: run migrations newer than the installed version

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Safe habits

  • Raise the version whenever you add a migration, and test the update on a copy of production data.
  • Never edit a published migration; add a new one.
  • Keep hooks idempotent (safe to run twice) where possible.
  • Do not delete user data in uninstall_hook unless the module owns it.
  • Use -u with --stop-after-init in deployment scripts so the server does not serve users during the update.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. When does Odoo run a post-init hook?

    pre_init runs before the tables are created, post_init after the install steps.
  2. 2. You removed a field from your Python model and updated the module. What happens to the column in PostgreSQL?

    Updates do not drop columns; cleaning up needs a migration script.
  3. 3. Why use a pre-migrate script to rename a column?

    If the new field name appears first, the ORM adds an empty column; renaming beforehand preserves the data.
  4. 4. What triggers Odoo to run a migration folder such as 18.0.1.1.0?

    Versions are compared during update, so remember to bump the manifest version.

Summary

  • Modules move between uninstalled, installed and to-upgrade states.
  • Install: dependencies, pre-init, Python and tables, data files, post-init.
  • Update re-reads data files and adds columns but does not drop removed fields or records.
  • Hooks (pre_init_hook, post_init_hook, uninstall_hook) are named in the manifest.
  • Migration scripts in migrations/<version>/ run when the version increases; back up before uninstalling anything.

Next: Defining Models and Fields