Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 39 ยท Concepts and Setup

Your First Module: Hello Odoo

Build a complete minimal Odoo module with a model, a list and form view, a menu and access rights, install it, and understand what each file contributes.

Time to build something. In this lesson you create a tiny module called vet_clinic with one model (vet.pet), screens to list and edit pets, a menu entry and permission for ordinary users. It has about five files, and together they use every concept from the previous lessons: manifest, imports, models, views, security and installation.

Odoo cannot run here, so the module files are shown as real, read-only code. The TryIt at the end is a stand-in that mimics the install pipeline in Python. The XML syntax follows the current series: since Odoo 18 the list view tag is <list>; in 17.0 and earlier it was <tree>.

Step 1: scaffold the folder

Run the scaffold command from the Odoo source folder (read-only):

Terminal
./odoo-bin scaffold vet_clinic custom-addons

It creates a ready-made vet_clinic folder with example files. We will replace them with our own, so you could also create the files by hand. Make sure custom-addons is in your addons_path.

Step 2: the manifest

Python
# vet_clinic/__manifest__.py
{
    "name": "Vet Clinic",
    "version": "18.0.1.0.0",
    "summary": "Register pets and their owners",
    "category": "Services",
    "license": "LGPL-3",
    "depends": ["base"],
    "data": [
        "security/ir.model.access.csv",
        "views/pet_views.xml",
    ],
    "application": True,
}

Step 3: the model

Python
# vet_clinic/__init__.py
from . import models

# vet_clinic/models/__init__.py
from . import pet

# vet_clinic/models/pet.py
from odoo import fields, models


class VetPet(models.Model):
    _name = "vet.pet"
    _description = "Pet"

    name = fields.Char(required=True)
    species = fields.Selection(
        [("dog", "Dog"), ("cat", "Cat"), ("other", "Other")],
        default="dog",
    )
    birthday = fields.Date()
    owner_id = fields.Many2one("res.partner", string="Owner")
    active = fields.Boolean(default=True)

Three details are worth naming. _name is the model's technical name and gives the table vet_pet. _description is a human-friendly label used in error messages and the access rights list. active is a special field: records with active = False are hidden from searches by default, which gives you "archive" for free.

Step 4: access rights

Without an access rule no ordinary user can see the new model (the administrator can). Create security/ir.model.access.csv:

TEXT
id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink
access_vet_pet_user,vet.pet user,model_vet_pet,base.group_user,1,1,1,0

The model_id:id value is the external id of the model, which Odoo generates as model_ plus the model name with dots replaced by underscores. base.group_user is the "Internal User" group. The last four columns are read, write, create and delete permissions.

Step 5: views, action and menu

XML
<!-- vet_clinic/views/pet_views.xml -->
<odoo>
  <record id="vet_pet_view_list" model="ir.ui.view">
    <field name="name">vet.pet.list</field>
    <field name="model">vet.pet</field>
    <field name="arch" type="xml">
      <list>
        <field name="name"/>
        <field name="species"/>
        <field name="owner_id"/>
      </list>
    </field>
  </record>

  <record id="vet_pet_view_form" model="ir.ui.view">
    <field name="name">vet.pet.form</field>
    <field name="model">vet.pet</field>
    <field name="arch" type="xml">
      <form>
        <sheet>
          <group>
            <field name="name"/>
            <field name="species"/>
            <field name="birthday"/>
            <field name="owner_id"/>
          </group>
        </sheet>
      </form>
    </field>
  </record>

  <record id="vet_pet_action" model="ir.actions.act_window">
    <field name="name">Pets</field>
    <field name="res_model">vet.pet</field>
    <field name="view_mode">list,form</field>
  </record>

  <menuitem id="vet_menu_root" name="Vet Clinic" action="vet_pet_action"/>
</odoo>

Read it top to bottom: two ir.ui.view records define the list and form, an ir.actions.act_window record says "open vet.pet with list and form views", and menuitem is a shortcut that creates a menu entry pointing to the action. Because the manifest says application: True and this menu has no parent, it appears as a top-level app tile.

Step 6: install

Restart with the module installed (read-only):

Terminal
./odoo-bin -d demo -i vet_clinic --addons-path=odoo/addons,addons,custom-addons

or, on a running server, enable developer mode, press Update Apps List in the Apps menu, search "Vet Clinic" and click Install. After installation, the Vet Clinic tile appears. Create a pet, save it, then check the vet_pet table in PostgreSQL to see your row.

When you later change a Python file, restart the server (or use --dev=reload). When you change an XML file or a field, upgrade the module with -u vet_clinic so the database copy of the data is refreshed.

What happened during install

flowchart TB
    A["1. Load depends (base)"] --> B["2. Import Python: models/pet.py"]
    B --> C["3. Create table vet_pet<br/>+ rows in ir_model, ir_model_fields"]
    C --> D["4. Load data files in order:<br/>access CSV, then views XML"]
    D --> E["5. Mark module as installed"]

Python first (so the model exists), then data files (so views can refer to it).

A runnable stand-in: the install pipeline

The following Python models the five steps with plain dictionaries. It is deliberately simple, but it shows why a manifest that lists a view before its model's access rule works (data files only need the model to exist) and what you can expect in the database afterwards.

Python Stand-in: simulate installing a module

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.

Common first-module mistakes

  • Forgetting the import in an __init__.py file: the model never loads.
  • Forgetting the access CSV: normal users get "You are not allowed to access" errors.
  • Listing a file in data with a wrong path: install stops with a file-not-found error.
  • Editing XML and only restarting without -u: the database still has the old view.
  • Using <tree> on a series that expects <list>, or the other way round.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does _name = "vet.pet" create in PostgreSQL?

    Dots in the model name become underscores in the table name.
  2. 2. A normal user reports 'You are not allowed to access Pet records'. What is missing?

    Models without access rules are only usable by the superuser. Add a line in ir.model.access.csv.
  3. 3. You changed a view's XML in an installed module. What must you do to apply it to the database?

    XML data is loaded into the database on install and update. A restart alone does not reload it unless dev xml mode is on.
  4. 4. What does the menuitem element do?

    menuitem is a shorthand for an ir.ui.menu record, here linked to the window action.

Summary

  • A minimal module needs a manifest, a Python model, an access rule, views, an action and a menu.
  • The model name vet.pet gives the table vet_pet; active provides archiving.
  • Python is imported first, then the data files listed in the manifest are loaded in order.
  • Restart for Python changes and upgrade (-u) for XML and field changes.
  • Most first-module bugs are missing imports, missing access rights and wrong paths.

Next: Module Dependencies and Loading Order