Odoo 19 Module Development Reference

File structure, conventions, commonly missed details, OWL introduction, and dev operations

🔗Module File Structure

Every Odoo module follows a standard directory layout. Not all folders are required. Only include what your module needs, but what you do include must follow this structure exactly.

    my_module/
    __manifest__.py          # Required. Without this, the folder is ignored.
    __init__.py              # Required. Makes this a Python package. must exist.
    
    # Models
    models/
        __init__.py          # Must import every model file in this directory.
        my_model.py
        my_model_line.py
    
    # Views
    views/
        my_model_views.xml   # Form, list, search, kanban views + actions + menus
        templates.xml        # QWeb templates (email, reports, snippets)
    
    # Security
    security/
        ir.model.access.csv  # Who can read/write/create/delete on each model
        ir.rule.csv          # Row-level rules (e.g. "only see own records")
        groups.xml           # Custom user groups / roles
    
    # Data (initial records, mail templates, sequences)
    data/
        mail_template.xml
        sequence.xml
    
    # Static assets (JS, CSS, images)
    static/
        description/
            icon.png         # Module icon. 120x120 transparent PNG.
        src/
            js/
                my_component.js   # OWL components
            xml/
                my_templates.xml  # QWeb templates for OWL
            css/
                style.css
    
    # Tests
    tests/
        __init__.py
        test_my_model.py
    
    # Wizards (transient multi-step flows)
    wizard/
        __init__.py
        my_wizard.py
        my_wizard_views.xml
    
    # Reports
    report/
        __init__.py
        my_report.py
        my_report_templates.xml

Only three things are truly mandatory: __manifest__.py, root __init__.py, and static/description/icon.png. Everything else is optional.

🔗manifest.py

The manifest tells Odoo everything about your module before loading it.

 1
 2    {
 3        # Internal technical name. Must be unique. Convention: snake_case.
 4        'name': 'My Module',
 5
 6        # Version: Odoo_major.series.iteration.patch.build
 7        'version': '19.0.1.0.0',
 8
 9        'summary': 'Does X and Y',
10
11        'description': """
12            Detailed explanation of what this module does.
13        """,
14
15        'author': 'Your Name',
16        'website': 'https://example.com',
17        'license': 'LGPL-3',
18        'category': 'Sales',
19
20        # Modules that must be installed first.
21        # If your code references sale.order, 'sale' MUST be here.
22        'depends': ['base', 'sale', 'mail'],
23
24        # Files loaded on install/update. ORDER MATTERS.
25        # Security first, then data, then views, then wizards/reports.
26        'data': [
27            'security/groups.xml',
28            'security/ir.model.access.csv',
29            'security/ir.rule.csv',
30            'data/mail_template.xml',
31            'views/my_model_views.xml',
32            'views/templates.xml',
33            'wizard/my_wizard_views.xml',
34            'report/my_report_templates.xml',
35        ],
36
37        # Demo data: only loaded in databases with demo data enabled.
38        'demo': ['data/demo_data.xml'],
39
40        'assets': {
41            'web.assets_backend': [
42                'my_module/static/src/js/my_component.js',
43                'my_module/static/src/css/style.css',
44            ],
45            'web.assets_qweb': [
46                'my_module/static/src/xml/my_templates.xml',
47            ],
48        },
49
50        'installable': True,
51        'auto_install': False,
52        'application': True,
53
54        'external_dependencies': {
55            'python': ['requests'],
56        },
57
58        # Hooks: format is 'file:function' (function at module root level)
59        'post_init_hook': '_post_init_hook',
60        'uninstall_hook': '_uninstall_hook',
61    }

Data file order is critical. Security files must come first. If a view references a model and its access CSV hasn't loaded yet, installation fails with an access error.

🔗Models (models/)

  1    # models/__init__.py
  2    # MUST import every model file. Miss one = Odoo doesn't discover it.
  3    from . import my_model
  4    from . import my_model_line
  5
  6    # models/my_model.py
  7    from odoo import models, fields, api, _
  8    from odoo.exceptions import ValidationError, UserError
  9
 10
 11    class MyModel(models.Model):
 12
 13        _name = 'my.module'
 14        _description = 'My Module Record'
 15        _order = 'name asc, create_date desc'
 16        _rec_name = 'name'
 17
 18        # ---- Field Types ----
 19
 20        name = fields.Char(string='Name', required=True, translate=True)
 21        description = fields.Text(string='Description')
 22
 23        state = fields.Selection([
 24            ('draft', 'Draft'),
 25            ('confirmed', 'Confirmed'),
 26            ('done', 'Done'),
 27            ('cancelled', 'Cancelled'),
 28        ], string='Status', default='draft', tracking=True)
 29
 30        priority = fields.Integer(string='Priority', default=0)
 31
 32        # Float: ALWAYS specify digits to avoid rounding issues.
 33        amount = fields.Float(string='Amount', digits=(10, 2))
 34
 35        # Monetary: use for currency amounts, NOT Float.
 36        total = fields.Monetary(string='Total', currency_field='currency_id')
 37        currency_id = fields.Many2one('res.currency', string='Currency')
 38
 39        # Many2one: foreign key. index=True on searched/grouped fields.
 40        partner_id = fields.Many2one(
 41            'res.partner', string='Customer',
 42            ondelete='set null', index=True,
 43        )
 44
 45        # One2many: inverse of Many2one. Virtual (not a real DB column).
 46        line_ids = fields.One2many('my.module.line', 'order_id', string='Lines')
 47
 48        # Many2many: stored via a relational table.
 49        tag_ids = fields.Many2many('my.module.tag', string='Tags')
 50
 51        date = fields.Date(string='Date')
 52        date_done = fields.Datetime(string='Done At')
 53
 54        # 'active' is special: False = archived, hidden from searches by default.
 55        active = fields.Boolean(string='Active', default=True)
 56
 57        # attachment=True: stores in ir.attachment instead of base64 in DB.
 58        document = fields.Binary(string='Document', attachment=True)
 59
 60        notes = fields.Html(string='Notes')
 61
 62        # ---- Computed Fields ----
 63        # store=True: required for search, sort, group by.
 64        # depends: fields that trigger recomputation when changed.
 65        display_name = fields.Char(compute='_compute_display_name', store=True)
 66
 67        def _compute_display_name(self):
 68            for rec in self:
 69                rec.display_name = rec.name or '(unnamed)'
 70
 71        # ---- Related Fields ----
 72        # Shortcut to a field on a related model. Same as computed+stored.
 73        partner_email = fields.Email(
 74            related='partner_id.email', string='Customer Email',
 75            readonly=False, store=True,
 76        )
 77
 78        # ---- Constraints ----
 79        _sql_constraints = [
 80            ('name_uniq', 'UNIQUE(name)', 'Name must be unique.'),
 81        ]
 82
 83        @api.constrains('amount', 'state')
 84        def _check_amount(self):
 85            for rec in self:
 86                if rec.state == 'confirmed' and rec.amount <= 0:
 87                    raise ValidationError(_('Amount must be positive when confirmed.'))
 88
 89        # ---- Methods ----
 90        # self is ALWAYS a recordset. Use 'for rec in self' for per-record logic.
 91
 92        def action_confirm(self):
 93            for rec in self:
 94                if rec.state != 'draft':
 95                    raise UserError(_('Only draft records can be confirmed.'))
 96            self.write({'state': 'confirmed'})
 97
 98        # ---- Overrides: always call super() ----
 99        def write(self, vals):
100            result = super().write(vals)
101            return result
102
103        def unlink(self):
104            for rec in self:
105                if rec.state == 'confirmed':
106                    raise UserError(_('Cannot delete confirmed records.'))
107            return super().unlink()
108
109
110    # ---- Transient Model (wizard) ----
111    class MyWizard(models.TransientModel):
112        _name = 'my.module.wizard'
113        _description = 'My Module Wizard'
114
115        date_from = fields.Date(required=True)
116        date_to = fields.Date(required=True)
117
118        def action_execute(self):
119            records = self.env['my.module'].search([
120                ('date', '>=', self.date_from),
121                ('date', '<=', self.date_to),
122            ])
123            return {'type': 'ir.actions.act_window_close'}

Access models via self.env['model.name'], never by importing the class. This ensures correct database, user context, and cache.

🔗Inheritance: Extending Existing Models

    # Inherit WITHOUT _name: extends the existing model in place.
    # This is what you want 95% of the time.
    from odoo import models, fields

    class SaleOrder(models.Model):
        _inherit = 'sale.order'

        my_custom_field = fields.Char(string='Custom Field')

        def action_confirm(self):
            result = super().action_confirm()
            return result

If you set both _name and _inherit, it creates a NEW model that copies the parent (prototype inheritance). This is rarely what you want.

🔗Useful Mixins

# Usage:
_name = 'my.module'
_inherit = ['mail.thread', 'mail.activity.mixin']

🔗Views (views/)

  1    # views/my_model_views.xml
  2    <?xml version="1.0" encoding="utf-8"?>
  3    <odoo>
  4
  5    <!-- FORM VIEW -->
  6    <record id="my_module_form" model="ir.ui.view">
  7        <field name="name">my.module.form</field>
  8        <field name="model">my.module</field>
  9        <field name="arch" type="xml">
 10            <form>
 11                <header>
 12                    <!-- type="object" calls a Python method -->
 13                    <button name="action_confirm" string="Confirm"
 14                            type="object" class="btn-primary"
 15                            invisible="state != 'draft'" />
 16                    <button name="action_done" string="Done"
 17                            type="object"
 18                            invisible="state != 'confirmed'" />
 19                    <button name="action_cancel" string="Cancel"
 20                            type="object"
 21                            invisible="state in ('done', 'cancelled')" />
 22                    <field name="state" widget="statusbar"
 23                           statusbar_visible="draft,confirmed" clickable="0" />
 24                </header>
 25
 26                <sheet>
 27                    <div class="oe_title">
 28                        <h1><field name="name" placeholder="Enter name..." /></h1>
 29                    </div>
 30                    <!-- GROUP: 4-col layout (label,field,label,field). col="2" for single col -->
 31                    <group>
 32                        <group string="Information">
 33                            <field name="partner_id" />
 34                            <field name="date" />
 35                        </group>
 36                        <group string="Amounts">
 37                            <field name="currency_id" />
 38                            <field name="amount" />
 39                            <field name="total" />
 40                        </group>
 41                    </group>
 42                    <notebook>
 43                        <page string="Lines">
 44                            <field name="line_ids">
 45                                <list editable="bottom">
 46                                    <field name="product_id" />
 47                                    <field name="quantity" />
 48                                    <field name="price_unit" />
 49                                </list>
 50                            </field>
 51                        </page>
 52                        <page string="Notes">
 53                            <field name="description" />
 54                            <field name="notes" />
 55                        </page>
 56                    </notebook>
 57                </sheet>
 58
 59                <!-- CHATTER: outside sheet. Requires mail.thread. -->
 60                <div class="oe_chatter">
 61                    <field name="message_follower_ids" />
 62                    <field name="message_ids" />
 63                </div>
 64            </form>
 65        </field>
 66    </record>
 67
 68    <!-- LIST VIEW -->
 69    <record id="my_module_list" model="ir.ui.view">
 70        <field name="name">my.module.list</field>
 71        <field name="model">my.module</field>
 72        <field name="arch" type="xml">
 73            <!-- decoration-*: danger, success, info, warning, muted -->
 74            <list string="Records"
 75                  decoration-danger="state == 'cancelled'"
 76                  decoration-success="state == 'done'">
 77                <field name="name" />
 78                <field name="partner_id" />
 79                <field name="amount" />
 80                <field name="state" widget="badge"
 81                       decoration-success="state == 'done'"
 82                       decoration-info="state == 'confirmed'"
 83                       decoration-danger="state == 'cancelled'" />
 84            </list>
 85        </field>
 86    </record>
 87
 88    <!-- SEARCH VIEW -->
 89    <record id="my_module_search" model="ir.ui.view">
 90        <field name="name">my.module.search</field>
 91        <field name="model">my.module</field>
 92        <field name="arch" type="xml">
 93            <search>
 94                <field name="name" />
 95                <field name="partner_id" />
 96                <filter name="draft" string="Drafts"
 97                        domain="[('state', '=', 'draft')]" />
 98                <separator />
 99                <filter name="by_partner" string="Customer"
100                        context="{'group_by': 'partner_id'}" />
101                <filter name="by_state" string="Status"
102                        context="{'group_by': 'state'}" />
103            </search>
104        </field>
105    </record>
106
107    <!-- ACTION -->
108    <record id="my_module_action" model="ir.actions.act_window">
109        <field name="name">My Records</field>
110        <field name="res_model">my.module</field>
111        <field name="view_mode">list,form</field>
112        <field name="view_id" ref="my_module_list" />
113        <field name="search_view_id" ref="my_module_search" />
114        <field name="context">{'search_default_draft': 1}</field>
115        <field name="help" type="html">
116            <p class="o_view_nocontent_smiling_face">Create your first record!</p>
117        </field>
118    </record>
119
120    <!-- MENUS -->
121    <menuitem id="my_module_menu_root" name="My Module" sequence="40" />
122    <menuitem id="my_module_menu_records" name="Records"
123              parent="my_module_menu_root" action="my_module_action" />
124
125    </odoo>

Chatter goes OUTSIDE <sheet>. Putting it inside won't render correctly.

🔗Security (security/)

    # security/ir.model.access.csv
    # id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink
    # group_id empty = public. base.group_user = all internal users.
    access_my_module_manager,my.module.manager,model_my_module,my_module.group_manager,1,1,1,1
    access_my_module_user,my.module.user,model_my_module,my_module.group_user,1,1,1,0

 1    # security/groups.xml
 2    <?xml version="1.0" encoding="utf-8"?>
 3    <odoo>
 4        <record id="module_category_my_module" model="ir.module.category">
 5            <field name="name">My Module</field>
 6        </record>
 7        <record id="group_user" model="res.groups">
 8            <field name="name">My Module User</field>
 9            <field name="category_id" ref="module_category_my_module" />
10            <field name="implied_ids" eval="[(4, ref('base.group_user'))]" />
11        </record>
12        <record id="group_manager" model="res.groups">
13            <field name="name">My Module Manager</field>
14            <field name="category_id" ref="module_category_my_module" />
15            <field name="implied_ids" eval="[(4, ref('my_module.group_user'))]" />
16        </record>
17    </odoo>

    # security/ir.rule.csv (optional)
    # Row-level security
    my_module_rule_user,my.module.user.rule,model_my_module,[('create_uid','=',user.id)],my_module.group_user,1,1,1,0

Missing ACL = silent access denied. If a model has no row in ir.model.access.csv, even admin gets errors in the UI.

🔗Data Files (data/)

 1    # data/sequence.xml (example)
 2    <odoo>
 3        <!-- noupdate="1": user modifications survive module updates -->
 4        <data noupdate="1">
 5            <record id="my_module_sequence" model="ir.sequence">
 6                <field name="name">My Module Sequence</field>
 7                <field name="code">my.module</field>
 8                <field name="prefix">MYM/</field>
 9                <field name="padding" eval="5" />
10            </record>
11        </data>
12    </odoo>

noupdate="1" matters. Without it, every module update resets sequences, mail templates, and settings to defaults, erasing user customizations.

🔗Static Assets (static/)

 1    # In __manifest__.py:
 2    'assets': {
 3        'web.assets_backend': [
 4            'my_module/static/src/js/my_component.js',
 5            'my_module/static/src/css/style.css',
 6        ],
 7        'web.assets_qweb': [
 8            'my_module/static/src/xml/my_templates.xml',
 9        ],
10        'web.assets_frontend': [
11            'my_module/static/src/js/website_stuff.js',
12        ],
13    },

After editing static files, clear your browser cache (Ctrl+Shift+R). In development, enable Developer Mode → Debug Assets or start Odoo with --dev=reload.

🔗Commonly Missed Things

1. Forgetting to import in __init__.py. Every model file must be imported in its directory's __init__.py, and every sub-directory in the root __init__.py.

2. Missing ACL entries. No row in ir.model.access.csv for a model = "Access Denied" when clicking the menu.

3. Wrong data file order in manifest. Security must load first.

4. Not calling super() in overrides. Silently breaks other modules overriding the same method.

5. Missing store=True on computed fields. Without it, can't search, sort, or group by that field.

6. No index=True on frequently searched Many2one fields.

7. Treating self as a single record. Always use for rec in self.

8. Not using _() for translatable strings.

9. Chatter inside <sheet>. Must be outside.

10. No noupdate="1" on user-configurable data.

11. Forgetting active filter. To include archived: [('active', 'in', [True, False])].

12. Using Float for money. Use fields.Monetary.

13. Not clearing cache after asset changes.

14. Duplicate XML IDs across modules. Last one loaded wins silently.

15. Using sudo() carelessly. Use with_user() when possible. Scope sudo() narrowly.

🔗Best Practices

• Prefix all XML IDs: my_module_form_view, not form_view
• Prefix model names: my_module.order, not order
• Use built-in automatic fields: create_date, write_date, create_uid, write_uid
• Keep models under ~30 fields — split with One2many if larger
• self.env.context.get('key') to read context safely
• with_context() to pass context without modifying current environment
• _logger = logging.getLogger(__name__) instead of print()
• Write tests for critical business logic
• Bump version after schema changes: 19.0.1.0.0 → 19.0.1.0.1
• Use useService("orm") over useService("rpc") in OWL

🔗OWL — Odoo Web Library: Introduction

OWL is Odoo's internal UI framework since Odoo 16, replacing the old odoo.Widget system. Not a general-purpose framework — built specifically for Odoo.

• Is: Lightweight component framework with reactive state, QWeb templates, lifecycle hooks. Similar concept to Vue/React but much smaller.
• Isn't: Usable outside Odoo. No router, no state library, no CLI.
• Replaces: odoo.Widget (Odoo 15 and earlier). If you see it, it's old code.
• Used for: Custom views, field widgets, client actions, systray items.

Reactivity loop: State changes → Template re-renders → DOM updates. Never touch the DOM directly.

🔗Where OWL Files Go

static/src/
    js/
        my_component.js     # Component class (web.assets_backend)
    xml/
        my_templates.xml   # QWeb templates (web.assets_qweb, NOT backend)
    css/
        style.css          # Use a scoping class name

🔗OWL vs Legacy Widget

They can coexist during migration. Start new components in OWL, migrate old ones incrementally.

🔗OWL Components

 1    # static/src/js/my_component.js
 2    /** @odoo-module */
 3    # Required for Odoo's bundler. Without it, imports break.
 4
 5    import { Component } from "@odoo/owl";
 6    import { registry } from "@web/core/registry";
 7    import { useService } from "@web/core/utils/hooks";
 8
 9    class MyCounter extends Component {
10
11        //Must match template's t-name exactly.
12        static template = "my_module.MyCounter";
13
14        //Declare expected props (optional but recommended).
15        static props = {
16            initialValue: { type: Number, optional: true },
17        };
18
19        setup() {
20            super.setup();  # MUST be first line
21
22            //State: reactive. Changing this.count triggers re-render.
23            this.count = this.props.initialValue || 0;
24
25            //Odoo services (singletons).
26            this.orm = useService("orm");
27            this.rpc = useService("rpc");
28            this.notification = useService("notification");
29            this.router = useService("router");
30            this.action = useService("action");
31        }
32
33        // ---- Lifecycle ----
34
35        async willStart() {
36            await super.willStart();
37            //Fetch initial data: this.data = await this.orm.searchRead(...)
38        }
39
40        mounted() {
41            super.mounted();
42            //DOM ready. Init third-party libs here.
43        }
44
45        willUnmount() {
46            super.willUnmount();
47            //CRITICAL: clean up timers, listeners, subscriptions.
48        }
49
50        # ---- Methods ----
51
52        increment() {
53            this.count++;  // No manual update. OWL detects change.
54        }
55
56        async saveToServer() {
57            try {
58                await this.orm.write("my.module", [this.props.recordId], {
59                    count: this.count,
60                });
61                this.notification.add({ type: "success", message: "Saved!" });
62            } catch (e) {
63                this.notification.add({ type: "danger", message: e.message });
64            }
65        }
66    }
67
68    //Register as client action (openable from menu).
69    registry.category("actions").add("my_module.counter_action", MyCounter);

🔗Common Odoo Services

🔗Lifecycle Order

🔗OWL Templates (QWeb)

 1    # static/src/xml/my_templates.xml
 2    <?xml version="1.0" encoding="UTF-8"?>
 3    <templates xml:space="preserve">
 4
 5    # t-name must match static template in component class
 6    <t t-name="my_module.MyCounter">
 7        <div class="my_counter">
 8
 9            # t-esc: escaped text (XSS safe). Use for all user data.
10            <h2><t t-esc="props.title or 'Counter'" /></h2>
11
12            # t-if: conditional. Element removed from DOM if false.
13            <div t-if="state.count > 10" class="alert alert-warning">
14                Count is getting high!
15            </div>
16
17            # t-attf-class: dynamic class with {{interpolation}}
18            <span t-attf-class="badge {{state.count > 0 ? 'bg-success' : 'bg-secondary'}}">
19                <t t-esc="state.count" />
20            </span>
21
22            # t-on-click: event. "->" calls a method.
23            <button class="btn btn-primary" t-on-click="increment">+</button>
24            <button class="btn btn-secondary" t-on-click="decrement">-</button>
25
26            # t-foreach + t-as + t-key (required for efficient DOM patching)
27            <ul>
28                <li t-foreach="state.items" t-as="item" t-key="item.id">
29                    <t t-esc="item.name" />
30                </li>
31            </ul>
32
33            # t-model: two-way binding on inputs
34            <input t-model="state.searchQuery" placeholder="Search..." />
35
36        </div>
37    </t>
38
39    </templates>

🔗Key QWeb Directives

t-key is required in loops. Use a unique stable ID, not an index.

🔗OWL Advanced

🔗Opening an OWL Component from a Menu

# In component JS:
registry.category("actions").add("my_module.counter_action", MyCounter);

# In views XML:
<record id="my_module_counter_action" model="ir.actions.client">
    <field name="name">My Counter</field>
    <field name="tag">my_module.counter_action</field>
    <field name="context">{'initial_value': 42}</field>
</record>

<menuitem id="my_module_menu_counter" name="Counter"
          parent="my_module_menu_root"
          action="my_module_counter_action" />

tag must match the registry key. Context dict is spread into props automatically.

🔗Component Composition (Parent + Child)

# static/src/js/child_component.js
/** @odoo-module */
import { Component } from "@odoo/owl";

class ChildBadge extends Component {
    static template = "my_module.ChildBadge";
    static props = { label: String, color: { type: String, optional: true } };
}

# static/src/xml/child_templates.xml
<?xml version="1.0" encoding="UTF-8"?>
<templates xml:space="preserve">
<t t-name="my_module.ChildBadge">
    <span t-attf-class="badge {{props.color || 'bg-secondary'}}"
          t-esc="props.label" />
</t>
</templates>

# Parent using the child
/** @odoo-module */
import { Component } from "@odoo/owl";
import { ChildBadge } from "./child_component";

class MyCounter extends Component {
    static template = "my_module.MyCounter";
    static components = { ChildBadge };  # REQUIRED: declare child components
}

<!-- In parent template XML: -->
<ChildBadge label="Active" color="bg-success" />
<ChildBadge label="Draft" />

🔗useState for Reactive Objects and Arrays

Plain objects/arrays on this are not deeply reactive. Use useState():

import { Component, useState } from "@odoo/owl";

class MyList extends Component {
    static template = "my_module.MyList";

    setup() {
        super.setup();
        this.state = useState({ items: [], loading: false });
    }

    async loadItems() {
        this.state.loading = true;
        this.state.items = await this.orm.searchRead("my.module", [], ["name"]);
        this.state.loading = false;
    }

    addItem(item) {
        # DON'T: this.state.items.push(item) -- OWL won't detect it.
        # DO: reassign the array.
        this.state.items = [...this.state.items, item];
    }

    removeItem(id) {
        this.state.items = this.state.items.filter(i => i.id !== id);
    }
}

Never mutate in place. push(), splice(), and direct property assignment on nested objects won't trigger re-renders. Always reassign.

🔗Event Bus for Cross-Component Communication

import { Component, useState, onWillUnmount } from "@odoo/owl";
import { useService } from "@web/core/utils/hooks";

# Emitter component:
class Emitter extends Component {
    setup() {
        super.setup();
        this.bus = useService("bus");
    }
    notifyOthers() {
        this.bus.emit("my_module:updated", { id: 42 });
    }
}

# Listener component:
class Listener extends Component {
    static template = "my_module.Listener";
    setup() {
        super.setup();
        this.bus = useService("bus");
        this.state = useState({ lastId: null });
        this._handler = this._handler.bind(this);
        this.bus.addEventListener("my_module:updated", this._handler);
        # MUST clean up:
        onWillUnmount(() => {
            this.bus.removeEventListener("my_module:updated", this._handler);
        });
    }
    _handler({ detail }) { this.state.lastId = detail.id; }
}

🔗Other Registration Types

# Custom field widget:
registry.category("fields").add("my_color_picker", MyColorPicker);
# Use: <field name="color" widget="my_color_picker" />

# Custom view type:
registry.category("views").add("my_custom_view", MyCustomView);
# Use: <field name="view_mode">list,my_custom_view</field>

🔗Common OWL Mistakes

1. Forgetting /** @odoo-module */ at top of JS files
2. Templates in wrong bundle. XML goes in web.assets_qweb, JS in web.assets_backend
3. Missing t-key in t-foreach
4. Not cleaning up in willUnmount() — memory leaks
5. Mutating arrays/objects in place — reassign instead
6. Mismatched t-name and static template — blank render, no error
7. t-raw with user data — XSS. Use t-esc
8. Missing static components = { Child } in parent
9. Not binding this in event callbacks — use .bind(this) or arrow functions
10. super.setup() not first line of setup()

🔗DevOps: CLI, PostgreSQL, Backups

🔗Starting Odoo

1    odoo-bin -c odoo.conf --dev=reload
2    # -c odoo.conf     : config file (recommended over CLI flags)
3    # --dev=reload      : auto-reload Python + assets on file changes
4    # --dev=all         : reload + verbose SQL logging + asset debug

Use a config file. CLI flags work but get unwieldy. Put database settings, paths, and addons paths in odoo.conf. Only use CLI flags for development overrides.

 1    # odoo.conf (minimal)
 2    [options]
 3    addons_path = /path/to/odoo/addons,/path/to/custom_addons
 4    db_host = localhost
 5    db_port = 5432
 6    db_user = odoo
 7    db_password = yourpassword
 8    http_port = 8069
 9    logfile = /path/to/odoo.log
10    log_level = info
11    # log_level: debug_sql shows all queries (slow but useful)

🔗Common CLI Commands

-i creates the database if it doesn't exist. Be careful — if you typo the database name, you get a fresh empty DB instead of updating your existing one. Always use -u for updates.

🔗Odoo Shell

 1The shell gives you a Python REPL with `self.env` (the Odoo environment) already set up. Useful for quick debugging without writing tests.
 2
 3    odoo-bin -c odoo.conf shell -d mydb
 4
 5    # Inside the shell:
 6    >>> self.env['sale.order'].search_count([])
 7    42
 8    >>> order = self.env['sale.order'].browse(1)
 9    >>> order.name
10    'SO001'
11    >>> order.partner_id.name
12    'Azure Interior'
13    >>> self.env['sale.order'].search([('state', '=', 'draft')], limit=5)
14    # Returns a recordset
15    >>> exit()

🔗Working with PostgreSQL

1    # Connect (default Odoo user is usually "odoo")
2    psql -U odoo -d mydb -h localhost
3
4    # If you get "peer authentication failed", use:
5    sudo -u postgres psql -d mydb

🔗Useful Queries

 1    --List all tables in the Odoo database
 2    \dt
 3
 4    --Describe a model's table structure (dots become underscores)
 5    \d sale_order
 6
 7    -- Count records in a model
 8    SELECT count(*) FROM sale_order;
 9
10    -- Find records by state
11    SELECT id, name, state FROM sale_order WHERE state = 'draft';
12
13    -- Check ir.model.access.csv coverage (models without ACL)
14    SELECT m.model
15    FROM ir_model m
16    LEFT JOIN ir_model_access a ON a.model_id = m.id
17    WHERE a.id IS NULL AND m.state = 'base';
18
19    -- List all installed modules
20    SELECT name, state FROM ir_module_module WHERE state = 'installed';
21
22    --Find which module owns a view (by XML ID)
23    SELECT * FROM ir_model_data WHERE name = 'my_module_form';
24
25    --Check table size (useful for finding bloated models)
26    SELECT relname AS table_name,
27           pg_size_pretty(pg_total_relation_size(relid)) AS size
28    FROM pg_stat_user_tables
29    ORDER BY pg_total_relation_size(relid) DESC
30    LIMIT 20;
31
32    --Kill all connections to a database (needed before dropping it)
33    SELECT pg_terminate_backend(pid)
34    FROM pg_stat_activity WHERE datname = 'mydb' AND pid <> pg_backend_pid();

Never modify Odoo tables directly via SQL unless you know exactly what you're doing. The ORM manages caches, computed fields, and triggers that raw SQL bypasses. For data fixes, use the shell or an _post_init_hook.

🔗Database Backup and Restore

🔗Method 1: CLI (recommended for automation/scripts)

    # Backup: dump the database
    pg_dump -U odoo -d mydb -F c -f mydb_backup.dump
    # -F c: custom format (compressed, supports parallel restore)

    # Restore: create a fresh database first
    createdb -U odoo mydb_restored
    pg_restore -U odoo -d mydb_restored -j 4 --no-owner mydb_backup.dump
    # -j 4: use 4 parallel jobs (much faster)
    # --no-owner: ignore original ownership (avoids permission issues)

    # Quick SQL dump (smaller file, slower restore)
    pg_dump -U odoo -d mydb -f mydb_backup.sql
    psql -U odoo -d mydb_restored -f mydb_backup.sql

🔗Method 2: Odoo UI (Settings → Database)

Go to http://localhost:8069/web/database/manager. Backup and restore from the browser. This handles the filestore (attachments) automatically.

Filestore is separate from the database. When using pg_dump, you only get the database. The filestore (actual file attachments stored on disk) lives at ~/.local/share/Odoo/filestore/mydb/. You must back this up separately. The UI backup handles this automatically.

    # Filestore location (default):
    ~/.local/share/Odoo/filestore/<database_name>/

    # Back it up:
    tar -czf mydb_filestore.tar.gz ~/.local/share/Odoo/filestore/mydb/

    # Restore it:
    tar -xzf mydb_filestore.tar.gz -C ~/.local/share/Odoo/filestore/
    # Make sure the folder name matches the new database name exactly.

🔗Complete Backup Script

    #!/bin/bash
    # backup_odoo.sh <database_name>
    # Usage: ./backup_odoo.sh mydb

    DB=$1
    DATE=$(date +%Y%m%d_%H%M%S)
    BACKUP_DIR="./backups/$DATE"
    FILESTORE_DIR="$HOME/.local/share/Odoo/filestore"

    mkdir -p $BACKUP_DIR

    echo "Dumping database..."
    pg_dump -U odoo -d $DB -F c -f "$BACKUP_DIR/${DB}.dump"

    echo "Backing up filestore..."
    if [ -d "$FILESTORE_DIR/$DB" ]; then
        cp -r "$FILESTORE_DIR/$DB" "$BACKUP_DIR/filestore"
    fi

    echo "Done: $BACKUP_DIR"

🔗Debug Mode

Activate via the URL: append ?debug=1 (or ?debug=assets for asset debugging only).

?debug=1 is persistent per session. Once activated, it stays on until you click "Leave Developer Mode" in the user menu or remove ?debug=1 from the URL.

🔗Logging

 1    # In Python code
 2    import logging
 3
 4    _logger = logging.getLogger(__name__)
 5
 6    # Use these instead of print():
 7    _logger.debug("Detailed info for debugging: %s", value)
 8    _logger.info("Normal operational info")
 9    _logger.warning("Something unexpected happened")
10    _logger.error("Something went wrong: %s", error.message)

 1    # In odoo.conf
 2    [options]
 3    # Log levels (from least to most verbose): critical, error, warning, info, debug
 4    log_level = warn
 5
 6    # Log only specific modules at debug level (very useful):
 7    log_handler = odoo.models:DEBUG
 8    log_handler = odoo.http:DEBUG
 9
10    # Log to file instead of stdout:
11    logfile = /var/log/odoo/odoo.log
12
13    # Log database queries (very slow, only for debugging):
14    # Either use --dev=debug_sql or:
15    log_level = debug_sql

log_handler with module-level filtering is the best approach. Instead of setting the entire log to debug (which floods output), log only the module you're working on: log_handler = odoo.addons.my_module:DEBUG.

🔗Development Workflow Tips

• Use --dev=reload during development. It watches Python files for changes and reloads the server automatically. No need to restart after every model change.
• Use --dev=all when debugging hard issues. It adds SQL query logging and asset debugging on top of reload.
• Keep your custom addons in a separate directory from the Odoo source. Point to both in addons_path. This makes updates and git management much cleaner.
• Use a separate database per project. Don't develop multiple features in the same DB. Create/restore backups to test fresh installs.
• Version your addons directory with git. Commit after every working change. Makes it trivial to revert when experiments go wrong.
• Test module install on a fresh database before deploying. Update-only testing misses issues in __init__.py, security CSV, and data files.
• Use odoo-bin scaffold to start new modules. It generates the correct folder structure, manifest, and init.py files.
• Don't edit core Odoo files. Ever. Always extend via inheritance. If you must patch core behavior, use _patch() or a monkey-patch in post_init_hook, and document it heavily.

🔗Odoo Technical Terms Reference

Comprehensive reference of key Odoo terms, their French translations, module locations, and workflow connections. Use this as a quick lookup for what each term means and where to find it in the UI.

Access paths by module:

• Sales / CRM: Ventes > Prospects, Commandes, Devis, Programme de fidélité
• Accounting: Comptabilité > Factures, Paiements, Rapprochement bancaire, Rapports
• Purchasing: Achats > Commandes fournisseurs
• Inventory: Stocks > Réceptions, Produits, Entrepôts, Mouvements de stock
• Manufacturing: Fabrication > Ordres de fabrication
• HR: Ressources Humaines > Paie, Congés
• Technical / Configuration: Comptabilité > Configuration > Plan comptable, Journaux, Taxes