How Custom Odoo Modules Work

Introduction#

You do not need to memorize every framework hook to ship a solid module, but you do need the skeleton: manifest, models, views, security, and data. Missing any one of those pieces produces modules that install with Access Errors or invisible menus.

This article walks the skeleton in the order you should build it, then explains install versus upgrade and `_inherit` behaviour you will use constantly.

__manifest__.py and module metadata#

Every module needs `__manifest__.py` (or legacy `__openerp__.py`) with at least `name`, `version`, `depends`, `data`, and usually `license` and `installable`. The `depends` list must include every module whose models or XML IDs you reference—typically `base` plus apps like `sale`, `stock`, or `account`.

List XML/CSV files in `data` (and `demo` if needed) in load order: security before views that need groups, data before menus that reference records. Set `application` only for true top-level apps. Keep `version` meaningful so operators know what shipped to production.

• ▸`depends`: hard requirements loaded before your module
• ▸`data`: security CSV/XML, views, actions, menus, cron, templates
• ▸`assets`: backend/frontend JS/CSS bundles when you extend the web client
• ▸`external_dependencies`: Python packages that must exist on the server

Models and the ORM#

Python files under `models/` define classes inheriting `models.Model`. Use `_name` for a new model and `_inherit` to extend an existing one (optionally with `_name` when creating a new model that also inherits behaviour). Register imports in `models/__init__.py` and the module root `__init__.py`.

Fields (`fields.Char`, `Many2one`, `One2many`, `Monetary`, etc.), `@api.depends` computes, `@api.constrains`, and overrides of `create`/`write`/`unlink` live here. Prefer extending standard methods with `super()` rather than copying entire methods. Keep business rules close to the model that owns the data.

Views XML and UI wiring#

View files declare `ir.ui.view` records. Extension views set `inherit_id` to the XML ID of a standard view and use XPath (`expr` + `position`) to insert fields, buttons, or pages. Primary views set a full `arch` for brand-new models.

Pair views with `ir.actions.act_window` and `menuitem` records so users can open them. Stable XML IDs matter: other modules, Studio, and tests will reference them. Target parent view IDs that Odoo documents as public extension points when possible.

Security CSV and record rules#

`security/ir.model.access.csv` grants model-level CRUD to groups (`perm_read`, `perm_write`, `perm_create`, `perm_unlink`). Without rows for a new `_name`, only the superuser can use the model—classic “Access Error” after install.

Record rules (`ir.rule` in XML) filter rows by domain for multi-company, salespeople seeing own documents, or warehouse isolation. Add rules intentionally; an empty or wrong global rule can hide all records or expose too much. Also create `res.groups` XML when your module introduces new roles instead of overloading `base.group_user`.

Data XML, dependencies, install vs upgrade#

Data XML creates noupdate-sensitive records: sequences, default stages, email templates, server actions. Use `noupdate="1"` for records operators may edit later so upgrades do not wipe their changes. Keep demo data in `demo` so production installs stay clean.

Installing a module (`-i`) creates schema and loads all data files. Upgrading (`-u`) reloads changed definitions: new fields, view updates, and updated CSV rights. After pulling Git changes that alter Python or XML, always upgrade the module on that database. Major version jumps may add `migrations/<version>/` scripts for data transforms.

• ▸Dev cycle: edit → restart/load → `-u your_module` on the DB → test
• ▸Never assume file save alone refreshes ORM fields in a running worker pool
• ▸Pin `depends` tightly; undeclared dependencies cause intermittent load failures

Inheritance deep dive: _inherit#

Classic extension: `_inherit = 'sale.order'` without a new `_name` patches the existing model in the registry. Classic delegation or prototype inheritance patterns exist for composition, but most business customizations use extension inheritance plus view inheritance.

When multiple modules inherit the same model, method Resolution Order (MRO) and `super()` chains matter. Keep overrides small, call `super()`, and avoid monkey-patching (`model.method = ...`) outside the ORM. If two modules fight over the same button, consolidate or coordinate depends order explicitly.

Practical recommendations#

• ✓Scaffold modules with security CSV on day one—even for prototype models.
• ✓Name XML IDs with a module prefix (`my_module.view_order_form_inherit`).
• ✓Prefer small `_inherit` methods with `super()` over pasted core methods.
• ✓Keep `depends` honest; add a dependency rather than duplicating a model.
• ✓Use staging databases to practice `-u` before production maintenance windows.
• ✓Add at least one smoke test or automated UI path for critical overrides.
• ✓Document required server restart / upgrade steps in the module README.

Common mistakes#

• !Forgetting `ir.model.access.csv` for new models.
• !Putting view XML in `data` before security groups those views reference.
• !Editing core addons instead of `_inherit` / `inherit_id`.
• !Changing Python fields locally and testing without module upgrade.
• !Using `noupdate="0"` on operator-owned data that upgrades keep resetting.
• !Circular or missing `depends` that only fail on clean database installs.

Conclusion#

Custom modules are predictable when you respect the skeleton: manifest dependencies, ORM models, XML views, security, and deliberate install/upgrade cycles. Inheritance keeps core code intact while letting you encode real process.

Once the skeleton is clear, invest in upgrade-friendly patterns and avoid the mistakes that make modules toxic at go-live—covered in the mistakes and best-practices articles.