Clean Odoo Workspaces: Managing Multiple Repositories with the Autoload Pattern

Managing custom Odoo development across multiple repositories often leads to a messy addons_path in your odoo.conf file. The Autoload Repos Pattern provides a clean, portable solution to manage unlimited repositories with relative symlinks without ever touching Odoo configuration files.

The Addons Path Dilemma

When working on complex Odoo implementations, developers and consultants frequently handle multiple codebases: standard Odoo modules, Odoo Enterprise addons, shared custom utilities, and client-specific custom modules. Adding each of these directory paths to the addons_path config leads to several issues:

• Configuration Bloat: A massive list of paths in odoo.conf that must be manually updated whenever a new module is added.
• Absolute Path Breakage: Hardcoded paths like /Users/vinay/workspace/vpcs_modules break when the workspace is moved, when a new developer clones the project, or when code is deployed to a staging VPS.
• Silent Failures: Typographic errors in absolute paths can prevent Odoo from loading custom modules, leading to long debugging sessions.

Introducing the Autoload Repos Pattern

The Autoload Repos pattern resolves these issues by using a hidden .autoload_repos/ directory inside your primary custom addons folder (typically extra-{V}/, e.g. extra-19/) to store repository checkouts, and then creating relative symlinks pointing to each Odoo module inside those repositories.

The Workspace Structure

With this pattern, your directory structure looks like this:

extra-19/                            ← Only this path is added to addons_path
  .autoload_repos/                   ← Hidden folder containing actual git clones
    vpcs_apps_cloud_19/              ← Repository clone A
      vpcs_llm_provider/             ← Odoo module folder
      vpcs_multi_agent/              ← Odoo module folder
    OdooConstruction/                ← Repository clone B
      construction_management/       ← Odoo module folder
  vpcs_llm_provider  →  .autoload_repos/vpcs_apps_cloud_19/vpcs_llm_provider  (relative symlink)
  vpcs_multi_agent   →  .autoload_repos/vpcs_apps_cloud_19/vpcs_multi_agent   (relative symlink)
  construction_management  →  .autoload_repos/OdooConstruction/construction_management (relative symlink)

Why Relative Symlinks?

Unlike absolute symlinks, relative symlinks (e.g., ln -s .autoload_repos/repo/module module) are resolved relative to the parent directory. This makes the entire workspace 100% portable:

Implementation Guide: Adding a Repo in 3 Commands

Adding a new module repository is straightforward and does not require editing odoo.conf:

# 1. Clone the repository into the hidden autoload folder
git clone git@github.com:org/my_repo.git extra-19/.autoload_repos/my_repo

# 2. Create a relative symlink from the extra-addons root
ln -s .autoload_repos/my_repo/my_module extra-19/my_module

# 3. Restart Odoo and update the module list
./manage_modules.sh update my_module

The Odoo Enterprise Exception

Because Odoo Enterprise contains hundreds of directories, creating individual symlinks for each is impractical. In this scenario, we use a hybrid approach:

1. Clone Odoo Enterprise to extra-19/.autoload_repos/ent-19/.
2. Add this directory directly as the second path in your addons_path configuration.
3. Create individual relative symlinks only for your custom project repositories.

Conclusion

By shifting repository organization from configuration files to the file system, the Autoload Repos pattern guarantees clean development workspaces, accelerates developer onboarding, and makes production deployments seamless. It is a DevOps standard that VPerfectCS uses across all client implementations.