Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 39 ยท Concepts and Setup

Module Structure and the Manifest

Learn the folder layout of an Odoo module and every key of __manifest__.py: name, depends, data, demo, assets, license, and how Odoo discovers modules.

A module is the unit of everything in Odoo. It adds models, views, data, security rules, reports and web assets, and it can be installed, upgraded and uninstalled as one piece. Because the structure is strictly conventional, a developer who has seen one module can find their way in any other, including the official ones.

This lesson dissects the folder layout and the manifest file. In the next lesson you will build a working module on top of it.

The folder layout

A module is a Python package (a folder with __init__.py) that also holds a __manifest__.py file. The standard layout, created by odoo-bin scaffold, is:

TEXT
library_book/
โ”œโ”€โ”€ __init__.py
โ”œโ”€โ”€ __manifest__.py
โ”œโ”€โ”€ models/
โ”‚   โ”œโ”€โ”€ __init__.py
โ”‚   โ””โ”€โ”€ book.py
โ”œโ”€โ”€ views/
โ”‚   โ””โ”€โ”€ book_views.xml
โ”œโ”€โ”€ security/
โ”‚   โ”œโ”€โ”€ ir.model.access.csv
โ”‚   โ””โ”€โ”€ security.xml
โ”œโ”€โ”€ data/
โ”‚   โ””โ”€โ”€ book_data.xml
โ”œโ”€โ”€ demo/
โ”‚   โ””โ”€โ”€ book_demo.xml
โ”œโ”€โ”€ controllers/
โ”‚   โ”œโ”€โ”€ __init__.py
โ”‚   โ””โ”€โ”€ main.py
โ”œโ”€โ”€ report/
โ”‚   โ””โ”€โ”€ book_report.xml
โ”œโ”€โ”€ static/
โ”‚   โ”œโ”€โ”€ description/icon.png
โ”‚   โ””โ”€โ”€ src/js/ ...
โ”œโ”€โ”€ i18n/
โ”‚   โ””โ”€โ”€ fr.po
โ””โ”€โ”€ tests/
    โ”œโ”€โ”€ __init__.py
    โ””โ”€โ”€ test_book.py

Only __init__.py and __manifest__.py are required. The other folders are conventions, and each has a purpose:

  • models/ Python classes that define or extend models.
  • views/ XML files with views, actions and menus.
  • security/ access rights (CSV) and record rules or groups (XML).
  • data/ XML or CSV records loaded at install and update (sequences, default settings, mail templates).
  • demo/ records loaded only into databases that have demo data.
  • controllers/ HTTP routes.
  • report/ QWeb report templates and report actions.
  • static/ files served to the browser: icon, JavaScript, CSS, images.
  • i18n/ translation files in the PO format.
  • tests/ automated tests.

The two __init__.py levels form the Python import chain. The top one imports the sub-packages and the sub-package imports each model file:

Python
# library_book/__init__.py
from . import models

# library_book/models/__init__.py
from . import book

If you forget an import line, your model file is simply never loaded, and Odoo shows no error, which is a classic first-day mistake.

The manifest

__manifest__.py contains a single Python dictionary literal. Odoo evaluates it safely to learn about the module. A complete example (read-only):

Python
{
    "name": "Library Books",
    "summary": "Manage a library catalogue",
    "description": "Long description (older style; use README.rst instead).",
    "version": "18.0.1.0.0",
    "category": "Services/Library",
    "author": "Your Company",
    "website": "https://example.com",
    "license": "LGPL-3",
    "depends": ["base", "mail"],
    "data": [
        "security/security.xml",
        "security/ir.model.access.csv",
        "views/book_views.xml",
        "data/book_data.xml",
    ],
    "demo": ["demo/book_demo.xml"],
    "assets": {
        "web.assets_backend": ["library_book/static/src/js/book.js"],
    },
    "application": True,
    "installable": True,
    "auto_install": False,
}
Key Meaning
name Human-readable title shown in Apps
summary One-line description
version Series plus module version (see Community, Enterprise and Versions)
category Groups modules in the Apps list
license Required in practice; common values are LGPL-3, GPL-3, OPL-1
depends Modules that must be loaded first. At minimum ["base"]
data Files loaded on install and update, in the order listed
demo Files loaded only when demo data is enabled
assets JavaScript, CSS and templates grouped into bundles
application True makes the module appear as a top-level app tile
installable False hides the module from installation
auto_install True installs the module automatically when all its dependencies are installed (a "glue" module)

The order of the data list matters. Security files usually come first, because views and menus can refer to groups defined there, and a view must exist before a menu refers to its action.

How Odoo discovers modules

At start, Odoo walks through every folder in addons_path. A subfolder that holds a __manifest__.py becomes a candidate module, and an entry is stored in ir_module_module. When you add a module folder to a running server, it does not appear in the Apps list until you click Update Apps List (in developer mode) or restart with -u base. Many "my module doesn't show up" problems come from this step, or from the folder not being inside a path listed in addons_path.

flowchart LR
    A["addons_path folders"] --> B["scan for __manifest__.py"]
    B --> C["ir_module_module<br/>state: uninstalled"]
    C -->|"Install"| D["load depends first,<br/>then python, then data files"]
    D --> E["state: installed"]

Installing a module loads its dependencies first, then its Python code, then its data files.

A runnable stand-in: a manifest checker

The manifest is a plain dictionary, so we can write a small validator in Python that checks the rules above. It is a stand-in for the checks Odoo and linters perform.

Python Stand-in: validate a manifest dictionary

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.

A second stand-in: loading data files in order

Another practical detail is that data files are processed in the listed order. The next stand-in shows why a view must come before the menu that points to it, using a tiny registry of external ids.

Python Stand-in: order of data files

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.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which files are the only ones strictly required in a module folder?

    A module is a Python package with a manifest. All other folders are conventions.
  2. 2. What does the depends key control?

    Odoo loads dependencies first, so your module can use their models and external ids.
  3. 3. Your new model never appears. You created models/book.py but nothing else. What is the most likely cause?

    Python only loads files that are imported. Odoo does not scan the models folder automatically.
  4. 4. What is the difference between data and demo in the manifest?

    Both are lists of data files, but demo files are skipped in databases created without demo data.

Summary

  • A module is a Python package plus __manifest__.py; other folders such as models/, views/ and security/ follow convention.
  • Imports in __init__.py files decide which Python files are loaded.
  • The manifest declares name, version, license, dependencies, data and demo files, assets and flags like application and auto_install.
  • Files in data load in order, so define groups and actions before using them.
  • New module folders must be in addons_path and the Apps list must be updated.

Next: Your First Module: Hello Odoo