Configuration files

OdooLS is using (since 0.8.0) configuration files to detect your odoo setup and use right configuration variables according to your needs. This allow us way more flexibility than settings.json files from VsCode, and make them valid for any IDE, so they are sharable too. We wanted something that can be highly customizable, but easy to use. So depending to your needs, you'll find here 3 ways to use OdooLS configuration files:

No configuration file

That's right! OdooLS can now work without any configuration files. By default, when you open a workspace, it will try to search for an Odoo directory, and check if addons directories exist at root workspace folder. If yes, a 'default' setup is used, using this odoo and these addons paths.

Basic configuration file

The first option has of course some limitations: what if you only open an addons directory? Or if you want to change python environment? If the default behaviour do not fit your needs, you can create a configuration file, named odools.toml in your filesystem. Let's create it at the root folder of your current workspace for now. We will discuss configuration file locations later The content of the configuration file is following the TOML syntax. Here is a valid content of a configuration file:

[[config]]
name = "My Config"
odoo_path = "/home/odoo/community"

This configuration file, if found at the root of your workspace, will indicate to OdooLS that it should use the Odoo sources located at /home/odoo/community, even if another odoo is opened in vscode.

We can add addons paths too:

addons_paths = ["/home/odoo/enterprise"]

or even use dynamic paths:

addons_paths = ["${workspaceFolder}"]

Important: Having multiple workspace folders with the same name is not allowed, and the server will refuse to start in this case. Make sure your workspace folders have unique names through your client

In this file, you can setup any setting of OdooLS. Here is a list of valid values:

Key	Type / Values	Description	Default
name	string	Name of the configuration profile	"default"
extends	string (optional)	Name of another profile in the same file to extend from	—
odoo_path	string (optional)	Path to the Odoo source code	—
addons_paths	array of string	List of addon directories to include	—
addons_merge	"merge" | "override"	How to combine addons_paths with parent profile	"merge"
python_path	string (optional)	Path to the Python interpreter	"python3"
additional_stubs	array of string	Additional stub directories	—
additional_stubs_merge	"merge" | "override"	How to combine additional_stubs with parent profile	"merge"
refresh_mode	"onSave" | "adaptive" | "off"	When to refresh the server data: onSave: when a file is saved adaptive: depending of the cost of a rebuild, it could be instantly or delayed until a period of inactivity (see auto_refresh_delay) off: never rebuild	"adaptive"
file_cache	bool	Enable file caching for workspace files	true
diag_missing_imports	"all" | "only_odoo" | "none"	Diagnostics for missing imports	"all"
ac_filter_model_names	bool	Only show model names from module dependencies in autocompletion	true
auto_refresh_delay	integer (min: 1000, max: 15000)	Delay in ms before refreshing after an update (values outside this range will be clamped)	1000
add_workspace_addon_path	bool	Add the workspace folder as an addon path if it looks like one and you specified other addons paths	false

When setting paths, you can use dynamic variables too: ${userHome}, ${workspaceFolder} or more specifically ${workspaceFolder:FOLDERNAME}

Advanced usage: multiple configuration files and profiles

This section will explain how to create and combine multiple configuration files and profiles.

Configuration files priority

To load configuration files, OdooLS will follow this sequence for each workspace folder:

• load configuration file in the folder
• search for another configuration file one folder above and load not already set variables

This allow you to create generic configuration file at a top level, like /home directory, and change various settings in some projects. But you can go further by using profiles:

Using profiles

When you write your configuration file, you can give a name to your set of variables. This will create a 'profile' that can be used in OdooLS. When opening your workspaces, if OdooLS find multiple profiles, you will be able to easily switch from one to another (see LINK on how to change your current profile according to your IDE) You can extend a profile too by using the keyword 'extends' followed by the name of a profile to indicate your are using this profile as a base for yours.

A complete example

Now that most of the features of configuration files has been explained, let's demonstrate the usage through an example.

File structure

The filesystem is filled with these files:

📁home/user/
├── 📄odools.toml
├── 📁community/
│   └── 📁other_odoo_files
└── 📁my_addons/
    ├── 📄odools.toml
    ├── 📁project_a
    |   └── 📁custom_module_1
    └── 📁project_b
        └── 📁custom_module_2

/home/user/odools.toml

[[config]]
name = "base_setup"
file_cache = false
odoo_path = "./community"

/home/user/my_addons/odools.toml

[[config]]
name = "project A"
extends = "base_setup"
addons_paths = ["./project_a"]

[[config]]
name = "project B"
extends = "base_setup"
addons_paths = ["./project_b"]

With this setup, when you open a directory like 'project_a', you can choose between the "project A" and "project B" profiles. You don't have to open the community folder anymore to get language server features.

However it means you have to select the right profile matching your current workspace (project_a or _b). We can even automatize that with this configuration:

[[config]]
name = "Current project"
extends = "base_setup"
addons_paths = ["${workspaceFolder}"]

With this file, each time you'll open a directory under my_addons, it will be loaded as an addon path of your odoo community, regardless its name !

Automatic Versionning

Let's go a little bit further now. Let's imagine you are working with different odoo versions, and you want to automatically detect them.

Here is a new filesystem example:

📁home/user/
├── 📄odools.toml
├── 📁community/
|   ├── 📁17.0
│   └── 📁18.0
└── 📁my_addons/
    ├── 📄odools.toml
    ├── 📁project_a
    |   ├── 📁17.0
    |   └── 📁18.0
    └── 📁project_b
        └── 📁18.0

Here, when we open project_a directory, we want it to load the directory as an addon of odoo 17, but odoo 18 for the project_b

There is two ways to achieve that. First, if the version is a directory name, we can set the special variable '$version' and use it in paths:

/home/user/odools.toml

[[config]]
name = "base_setup"
file_cache = false
"$version" = 18.0
odoo_path = "./community/${version}"

Note: The key "$version" is quoted because TOML keys containing special characters (like $) must be quoted. This is valid TOML syntax and allows the use of variable-like keys.

/home/user/my_addons/odools.toml

[[config]]
"$version" = "${workspaceFolder}/${detectVersion}"
# Note: The variable ${detectVersion} is a special placeholder that OdooLS will automatically resolve to the detected version number
# based on the directory structure or naming conventions in your workspace.
addons_paths = ["${workspaceFolder}/${version}"]

then if you open 'project_a', you will have two available profiles: "Current Project (17.0)" and "Current Project (18.0)". Depending on your choice, the corresponding Odoo will be chosen.