Understanding Odoo Module Structure

Introduction#

Before writing fields or xpath expressions, know where they live. Odoo's module loader is opinionated — fighting its layout creates fragile addons that break on the next install.

This article maps the standard directory tree, manifest keys that matter in Odoo 16/17, and how files are processed during module install and upgrade.

The manifest as contract#

__manifest__.py defines technical name, human title, version, depends, application flag, and the ordered data list. Odoo processes data files top to bottom; security CSV before views that reference new models, demo data last.

Use semantic versioning aligned with your Odoo target (e.g. 17.0.1.0.0). Bump the version on every -u-worthy change so operators know staging must run an upgrade.

• ▸depends: only what you import or inherit at load time
• ▸data vs demo: keep demo out of production installs
• ▸assets: register JS/SCSS under web.assets_backend when needed
• ▸post_init_hook / uninstall_hook: sparingly, document side effects

Python package layout#

models/__init__.py imports each model file; each file typically defines one Model class. Wizards go in wizard/, controllers in controllers/, report Python in report/. Keep __init__.py at module root importing subpackages.

Use _inherit for extending existing models and _name only when defining new business tables. Split large domains into multiple files (sale_custom.py, sale_custom_line.py) rather than thousand-line monoliths.

XML, security, and static assets#

views/ holds form, list, kanban, search, and inherited view XML. security/ holds ir.model.access.csv and record-rule XML. data/ holds cron, mail templates, sequences, and noupdate=1 master data when appropriate.

static/description/icon.png and index.html power the Apps list. i18n/*.po files sit at module root for translations.

Dependencies and load order#

If module B inherits views or models from module A, B must list A in depends. Circular depends are rejected; implicit ordering via auto_install is for Odoo core patterns, not ad-hoc shortcuts.

For multi-company or bridge modules (sale_stock_custom), create thin glue modules rather than stuffing cross-app logic into one mega-addon.

Naming and repository hygiene#

Prefix custom modules with your company or project code (kitech_sale_approval) to avoid collisions with App Store modules. One Git repo can hold many addons; document addons_path for each environment.

Never edit files under odoo/addons or enterprise paths — only your addons_path. Forked core changes are upgrade blockers.

Practical recommendations#

• ✓Maintain a module template with manifest, security stub, and empty model scaffold.
• ✓List every XML/CSV in data; verify fresh -i on a clean DB before merging.
• ✓Split modules by bounded context — sales approval vs manufacturing routing should not share one manifest.
• ✓Document depends rationale in README or module description for future reviewers.
• ✓Keep hooks idempotent; post_init_hook should tolerate re-run after failed upgrade.
• ✓Align folder names with Odoo conventions so IDE search and Odoo.sh builds stay predictable.

Common mistakes#

• !Adding XML files without updating __manifest__.py data list.
• !Depending on sale_management when only sale is required — pulls unnecessary UI.
• !Putting business logic in XML automated actions instead of Python models.
• !Using duplicate technical module names across projects copied from GitHub.
• !Mixing translation strings and hard-coded labels without _() in Python.
• !Creating circular depends by importing models at module level across addons.

Conclusion#

Module structure is not bureaucracy — it is how Odoo finds, secures, and upgrades your code. A clean manifest and folder layout pays back on every -u.

Next, learn how the ORM loads these models and executes create/write/unlink in transactions.