Easy Odoo Folder Structure: 3 Steps to Master

Source Video: Understanding Odoo Folder Structure ｜ Beginners Guide to Odoo Development ｜ Odoo 18

Are you diving into Odoo development and feeling overwhelmed by the myriad of files and directories? Understanding the Odoo Folder Structure is not just a technicality; it’s a foundational skill that empowers you to navigate, customize, and build robust Odoo applications efficiently. Mastering this Odoo folder structure ensures a smoother development workflow and easier maintenance.

Whether you’re a seasoned developer or just starting your journey with this powerful ERP system, a clear grasp of its directory layout is crucial for successful module creation, debugging, and system maintenance. Without a solid understanding of where different components reside and how they interact, even simple tasks can become unnecessarily complex.

This comprehensive guide will walk you through the essential components of Odoo’s file organization, offering a step-by-step tutorial designed to demystify its architecture. We’ll explore the three fundamental layers that make up the Odoo system, ensuring you gain a profound understanding of where everything resides and why.

Odoo’s architecture is intelligently organized into three primary layers, each with its distinct purpose:

The Root Structure: The core foundation of your Odoo installation.
The Add-ons (Modules) Structure: Where Odoo’s standard applications and your custom developments reside.
Special Paths for Custom Modules: How to integrate your bespoke solutions seamlessly.

Let’s embark on this journey to master the Odoo folder structure and unlock your full development potential.

Table of Contents

Step 1: Navigating the Odoo Root Folder Structure

The root directory represents the highest level of your Odoo installation. It’s the starting point from which all other components branch out. When you first download Odoo from GitHub or perform a fresh installation, this is the primary directory you interact with. Understanding the Odoo folder structure begins with its root, which contains the essential files and folders that allow Odoo to run, along with its core applications.

Accessing the Odoo Root Folder

Typically, this folder is created when you clone the Odoo repository from GitHub, download a release archive, or install Odoo via package managers. Its location might vary based on your operating system and installation method (e.g., /opt/odoo on Linux, or within your Python virtual environment). This foundational layer defines the primary Odoo folder structure that all other components build upon.

Key Components within the Odoo Root Folder Structure

Understanding the purpose of each item in the root directory is vital for system administration, initial setup, and troubleshooting common deployment issues.

addons Folder:
This is arguably the most critical folder within the root structure. It houses all of Odoo’s official, “base” modules that come pre-installed with your Odoo instance. These are the applications that provide core ERP functionalities, such as:
- sales: Manages sales orders, quotations, and customer relationships.
- purchase: Handles procurement processes, vendor management, and purchase orders.
- crm: Customer Relationship Management tools for lead tracking and opportunity management.
- inventory: Controls stock levels, warehousing, and logistics.
- accounting (or account): Manages financial transactions, ledgers, and reporting.
- Why it’s important: These modules form the backbone of Odoo’s capabilities. Developers often refer to these core modules to understand best practices, design patterns, and how specific functionalities are implemented within the overall Odoo folder structure.
odoo Folder:
This directory contains the very heart of the Odoo framework itself. It’s where the magic happens – the core Python libraries, database abstractions, web controllers, API definitions, and various utility tools that Odoo relies upon to function. When you import odoo modules in your custom code (e.g., from odoo import models, fields), you’re accessing components defined within this folder. It’s the engine that powers the entire ERP system. This folder is key to understanding the deep technical intricacies of the Odoo folder structure.
- Inside odoo: You’ll find sub-folders like models, fields, http (for web controllers), api, and tools, each serving specific architectural purposes.
odoo-bin:
This executable file is the main command-line script used to run, manage, and interact with your Odoo instance. Whether you’re starting the server, updating modules, or running tests, odoo-bin is your primary interface. It contains the necessary code to parse commands and execute Odoo operations.
- Usage Example: python3 odoo-bin -c /etc/odoo.conf to start the server with a specific configuration file. It’s the entry point that brings the entire Odoo folder structure to life.
requirements.txt:
This plain text file lists all the Python third-party libraries and their specific versions required for Odoo to run correctly. When you set up a new Odoo environment, you’ll typically use pip install -r requirements.txt to install these dependencies. It’s crucial for maintaining compatibility and ensuring a stable environment, as different Odoo versions might require distinct library versions.
- Best Practice: Always install these requirements in a dedicated Python virtual environment to avoid conflicts with other Python projects on your system. For more information on virtual environments, consult the official Python documentation on venv.
setup.py:
This script is part of Odoo’s packaging and installation process. It defines how Odoo itself can be installed as a Python package. For developers, this file is less frequently directly interacted with but plays a crucial role behind the scenes when you install Odoo from source or distribute it, influencing how Odoo’s core components are set up within the system’s directory layout.
MANIFEST.in:
While less frequently discussed in beginner guides, this file is part of Python’s setuptools and specifies non-Python files (like XML, images, CSS, JS) that should be included in the source distribution when packaging Odoo. It ensures that all necessary assets are bundled correctly, contributing to the integrity of the shipped Odoo folder structure.

Step 2: Demystifying the Odoo Add-ons (Modules) Folder Structure

Once you understand the root, the next logical step is to delve into the addons directory – the heart of Odoo’s modularity. Every piece of functionality in Odoo, whether it’s a core feature like sales or a custom business process, is encapsulated within a module. Understanding the internal Odoo folder structure of a module is paramount for anyone looking to develop or customize Odoo. Every developer must master the module’s internal Odoo folder structure to effectively contribute to Odoo.

Let’s take a typical Odoo module, for instance, the sale module or any custom module you create, and break down its essential components. This standard module architecture ensures consistency and ease of development across the Odoo ecosystem.

Core Files and Folders within an Odoo Module

A standard Odoo module follows a predictable and logical structure, making it easier to manage and scale applications.

__init__.py (External Initialization File):
This special Python file signals to Odoo (and Python itself) that the directory it resides in is a Python package. It’s the first file Odoo looks at when loading a module. Its primary role is to import other Python files or sub-folders within the module, effectively linking all the Python logic together.
- Example Content: from . import models, wizards (imports the models and wizards folders).
- Importance: Without this file, Odoo wouldn’t be able to discover or load your module’s Python code, making it a cornerstone of the module’s Odoo folder structure.
__manifest__.py (Module Manifest File):
Often considered the “ID card” of your module, this crucial file (formerly __openerp__.py in older Odoo versions) provides metadata about the module in JSON format. Odoo uses this information to display the module in the Apps list, manage dependencies, and determine how the module should behave. This comprehensive file ensures Odoo correctly recognizes and manages your module within the broader Odoo folder structure.
- Key Attributes:
  - name: The human-readable name displayed in the Odoo Apps menu (e.g., “Sales Management”).
  - version: The module’s version number (e.g., '16.0.1.0.0').
  - summary: A short description of the module’s purpose.
  - description: A more detailed explanation, often including features and usage.
  - author: The developer or organization behind the module.
  - website: A link to the author’s website or project page.
  - category: The module’s functional category (e.g., ‘Sales’, ‘Accounting’).
  - depends: A list of technical names of other Odoo modules that this module relies on (e.g., ['base', 'mail']). If dependencies are not met, the module cannot be installed.
  - data: A list of XML or CSV files containing views, security rules, demo data, etc., to be loaded upon module installation or update.
  - demo: A list of XML or CSV files specifically for demo data, loaded only if demo mode is enabled.
  - installable: Boolean, whether the module can be installed (defaults to True).
  - application: Boolean, if set to True, the module appears as a main app in the Odoo dashboard.
  - auto_install: Boolean, if True, the module is automatically installed if all its dependencies are met.
- Practical Tip: Always keep your __manifest__.py up-to-date, as it’s the primary source of information for module management and directly impacts how your module is perceived and loaded within the Odoo folder structure. For a detailed list of all possible attributes and their uses, refer to the official Odoo Developer Documentation.
models Folder:
This sub-folder is dedicated to your module’s Python business logic. It contains .py files where you define Odoo models, which represent database tables and encapsulate data validation, computations, and business rules.
- Structure within models:
  - __init__.py (Internal Initialization File): This __init__.py file (distinct from the main module’s __init__.py) is responsible for importing all the individual model files within the models folder. For example, if you have sale_order.py and product_template.py inside models, this __init__.py would contain from . import sale_order, product_template.
  - Individual Model Files (e.g., sale_order.py, customer.py): Each file typically defines one or more Odoo models, inheriting from models.Model, models.TransientModel, or models.AbstractModel.
- The __init__.py Linkage Explained: The external __init__.py (at the module’s root) imports the models folder. The internal __init__.py (inside the models folder) then imports the individual Python files containing your model definitions. This hierarchical import structure is fundamental to how Odoo discovers and loads your models and impacts the overall Odoo folder structure. Understanding this nested __init__.py hierarchy is fundamental to comprehending the Python aspect of the Odoo folder structure.
views Folder:
This folder is where you define the user interface (UI) components of your module using XML files. Odoo’s UI is largely declarative, meaning you describe what you want the interface to look like in XML, and Odoo renders it.
- Common Files/Types:
  - Form views: For detailed record editing.
  - Tree views (List views): For displaying lists of records.
  - Search views: For filtering and grouping records.
  - Kanban views: For a visual, card-based representation.
  - Calendar views, Graph views, Pivot views, etc.
  - Menu items (<menuitem>): To add entries to the Odoo navigation.
  - Actions (<record model="ir.actions.act_window">): To define what happens when a menu item is clicked (e.g., opening a view).
- Tip: Organize your views logically within the folder (e.g., sale_order_views.xml, product_template_views.xml) for better readability within the module’s Odoo folder structure.
data Folder:
Used for loading static data into Odoo upon module installation. This data is not typically user-modifiable through the UI but provides default configurations, predefined records, or system settings.
- Use Cases:
  - Default settings for a module.
  - Pre-configured record types (e.g., specific product categories, tax types).
  - Scheduler actions that run automatically.
security Folder:
Crucial for defining access control within your module. It contains XML files that specify user groups, record rules, and access rights (read, write, create, unlink) for different Odoo models.
- Key File: ir.model.access.csv is a common file here, defining basic access rights for models based on user groups.
- Best Practice: Always define the minimum necessary access rights. Do not grant unnecessary permissions, as this is a vital aspect of a secure Odoo folder structure.
report Folder:
This folder is dedicated to custom report templates, typically generated in PDF or HTML formats. Odoo uses a templating engine called QWeb for reports.
- Contents: XML files defining the report’s structure and data source, and potentially Python files for complex report logic.
- Examples: Sales Order reports, Purchase Order reports, Invoice reports.
static Folder:
Contains all static assets that are served directly by the web browser. This includes client-side resources that enhance the user interface and overall module presentation.
- Common Sub-folders:
  - description: For markdown or HTML files describing the module for the Odoo App Store.
  - img or static/src/img: Module icon (e.g., icon.png), images used in views or reports.
  - lib: External JavaScript or CSS libraries.
  - src: Often contains css, js, xml for web assets like custom styling, client-side scripts, and QWeb templates for the web client.
- Module Icon: The icon.png or icon.svg file within static/description is displayed next to your module in the Odoo Apps list. Proper organization of assets within this part of the Odoo folder structure is crucial for web performance and module presentation.
wizard Folder:
Houses Python files and associated XML views for “transient models” or “wizards.” These are temporary data forms used for multi-step processes or pop-up dialogues that don’t need persistent storage in the main database.
- Typical Use: Batch actions, configuration steps, data import/export assistants.
tests Folder:
Contains Python files for writing unit tests and integration tests for your module. This is a best practice to ensure the functionality you develop works as expected and doesn’t break with future updates or changes.
- Importance: Robust testing saves development time and ensures the reliability of your Odoo applications. Integrating tests effectively is a sign of a well-maintained Odoo folder structure for a module.

Step 3: Integrating Your Custom Odoo Modules via Special Paths

Developing custom modules is a cornerstone of extending Odoo’s capabilities to meet specific business needs. However, simply creating a module folder isn’t enough; Odoo needs to know where to find your bespoke creations. This is where the concept of “special paths” for custom modules comes into play, ensuring your developments are recognized and installable within your Odoo instance. This critical step completes your understanding of the Odoo Folder Structure.

The Rationale for Custom Add-ons Paths

While you could place your custom modules directly into the main addons folder of your Odoo installation, it’s considered a poor practice. Why?

Separation of Concerns: Keeps your custom code separate from Odoo’s core modules, simplifying upgrades and maintenance.
Version Control: Allows you to manage your custom modules in their own version control repositories without interfering with the Odoo core repository.
Deployment: Makes it easier to deploy specific custom modules across different Odoo instances.
Clarity: A clear separation helps quickly distinguish between core Odoo features and your specific customizations.

For these reasons, it’s highly recommended to create a dedicated directory for your custom add-ons. Adhering to best practices for the custom Odoo folder structure simplifies upgrades and makes collaborative development more straightforward.

How to Configure Custom Add-ons Paths

The addons_path parameter in your Odoo configuration file (odoo.conf) is the key to telling Odoo where to look for modules. This configuration is a fundamental part of managing your Odoo folder structure for custom development.

Create Your Custom Modules Folder:
First, establish a new directory on your server or development machine where you will store all your custom Odoo modules.
- Example: /opt/odoo/custom_addons or ~/odoo-dev/my_custom_modules.
- Inside this folder: You’ll create sub-folders for each of your custom modules, following the __manifest__.py, models, views, etc., structure as detailed in Step 2. For instance:
```
/opt/odoo/custom_addons/
├── my_first_custom_module/
│   ├── __init__.py
│   ├── __manifest__.py
│   ├── models/
│   │   └── __init__.py
│   │   └── my_model.py
│   └── views/
│       └── my_view.xml
└── another_custom_module/
    ├── ... (similar structure)
```
Locate and Edit odoo.conf:
The odoo.conf file is Odoo’s primary configuration file. Its location can vary depending on your installation method and operating system:
- Default Locations:
  - /etc/odoo/odoo.conf (common for system-wide installations)
  - ~/.odoorc (user-specific configuration)
  - In the directory where you run odoo-bin if no other config is specified.
- Tip: If you can’t find it, running odoo-bin for the first time (e.g., odoo-bin --save-config) will often create a default odoo.conf file in the current directory or a standard location. Knowing where to modify addons_path is a practical application of understanding the Odoo folder structure.
Open this file using a text editor (e.g., nano, vi, VS Code).
Modify the addons_path Parameter:
Inside odoo.conf, find the addons_path parameter. It typically lists the default Odoo add-ons folder. You need to append your custom modules folder to this list, separating multiple paths with a comma.
- Before (Example):
```
addons_path = /path/to/your/odoo/installation/addons
```
- After (Example):
```
addons_path = /path/to/your/odoo/installation/addons,/opt/odoo/custom_addons
```
- Crucial Permission Check: Ensure that the operating system user account under which the Odoo server process runs has sufficient permissions (at least read and execute) for your newly added custom add-ons folder and its contents. Incorrect permissions will prevent Odoo from loading your modules, regardless of correct path configuration.
Restart the Odoo Server:
After saving changes to odoo.conf, it’s essential to restart your Odoo server. Odoo reads its configuration files only at startup, so changes to addons_path won’t take effect until a restart. This step is critical for Odoo to acknowledge the new additions to its effective Odoo folder structure.
Update the Modules List in Odoo:
Once the server is back up:
- Log in to your Odoo instance as an administrator.
- Navigate to the “Apps” module.
- Activate “Developer Mode” (often found in the user menu, accessible by clicking your name in the top right corner).
- Click on “Update Apps List” (or “Update Modules List”). This action forces Odoo to scan all directories specified in addons_path for new or updated modules and refreshes the list displayed in the Apps module.
Install Your Custom Module:
Finally, you can search for your custom module by its name (as defined in __manifest__.py) in the Apps module and click “Install.” This will bring your custom functionality into your Odoo instance, seamlessly integrated thanks to your careful management of the Odoo folder structure.

By following these steps, you not only integrate your custom solutions into your Odoo environment but also adhere to best practices for maintainability and scalability. A well-organized Odoo folder structure for your custom add-ons is a hallmark of professional Odoo development.

Conclusion: Mastering Your Odoo Ecosystem

A deep understanding of the Odoo Folder Structure is more than just knowing where files are; it’s about comprehending the architectural design that makes Odoo so powerful and flexible. From the foundational root directories to the intricate organization within each module and the strategic placement of custom add-ons, every piece serves a vital role in the system’s operation and overall efficiency.

By grasping these three essential layers – the root structure, the internal module organization, and the process of integrating custom paths – you gain the confidence to:

Navigate with Ease: Quickly locate files for debugging, modification, or reference within the complex web of Odoo’s directories.
Develop Efficiently: Structure your custom modules logically, ensuring maintainability, scalability, and easy collaboration for future projects.
Troubleshoot Effectively: Pinpoint issues related to missing dependencies, incorrect file placements, or access rights with precision.
Ensure Smooth Upgrades: Keep your custom code isolated from the core, making future Odoo version upgrades significantly simpler and less prone to conflicts.

This guide has provided you with a comprehensive, step-by-step walkthrough to conquer the Odoo folder structure. Remember, consistent practice and hands-on experience are key to truly mastering Odoo’s file organization. With this knowledge, you are well-equipped to build, customize, and manage robust Odoo applications with greater proficiency. Happy developing!

Discover more from teguhteja.id

Subscribe to get the latest posts sent to your email.

Easy Odoo Folder Structure: 3 Steps to Master

Step 1: Navigating the Odoo Root Folder Structure

Accessing the Odoo Root Folder

Key Components within the Odoo Root Folder Structure

Step 2: Demystifying the Odoo Add-ons (Modules) Folder Structure

Core Files and Folders within an Odoo Module

Step 3: Integrating Your Custom Odoo Modules via Special Paths

The Rationale for Custom Add-ons Paths

How to Configure Custom Add-ons Paths

Conclusion: Mastering Your Odoo Ecosystem

Like this:

Related

Discover more from teguhteja.id

Leave a ReplyCancel reply

Easy Odoo Folder Structure: 3 Steps to Master

Step 1: Navigating the Odoo Root Folder Structure

Accessing the Odoo Root Folder

Key Components within the Odoo Root Folder Structure

Step 2: Demystifying the Odoo Add-ons (Modules) Folder Structure

Core Files and Folders within an Odoo Module

Step 3: Integrating Your Custom Odoo Modules via Special Paths

The Rationale for Custom Add-ons Paths

How to Configure Custom Add-ons Paths

Conclusion: Mastering Your Odoo Ecosystem

Share this:

Like this:

Related

Discover more from teguhteja.id

Leave a ReplyCancel reply