Skip to main content
OdooLS is configured through an odools.toml file written in TOML format. When a workspace is opened, OdooLS walks up the directory tree from the workspace root until it finds an odools.toml file (or reaches the filesystem root). You can also supply an explicit path with the --config-path CLI flag.
You can place odools.toml in the repository root, any parent directory, or supply it explicitly with --config-path.

​
File structure

The file contains one or more [[config]] sections (a TOML array of tables). Each section defines a named profile. See Configuration Profiles for details on how profiles inherit from each other. 
[[config]]
name = "default"
odoo_path = "/opt/odoo/17.0"
addons_paths = ["/opt/odoo/custom_addons", "$autoDetectAddons"]
python_path = "python3"
diag_missing_imports = "only_odoo"
auto_refresh_delay = 500
file_cache = true

​
Configuration fields

​
Core identity

​
name
string
default:"default"
The profile name. Each [[config]] section must have a unique name. The built-in fallback profile is always named "default".
​
extends
string
Name of another profile to inherit settings from. Child settings take precedence over parent settings. Array fields (addons_paths, additional_stubs) are merged according to their respective *_merge fields. Circular dependencies are detected and rejected. See Configuration Profiles for a full inheritance example.

​
Paths

​
odoo_path
string
Absolute path to the Odoo community source directory. OdooLS validates that the directory looks like a valid Odoo installation. If exactly one workspace folder is a valid Odoo path and odoo_path is not set, it is inferred automatically.
odoo_path = "/opt/odoo/17.0"
​
addons_paths
string[]
List of directories that contain Odoo addon modules. Supports the special value "$autoDetectAddons": when present, OdooLS checks whether the current workspace folder itself is a valid addon directory and adds it automatically.Path variables ${workspaceFolder:NAME} and ${userHome} are supported.
addons_paths = [
  "/opt/odoo/17.0/addons",
  "/opt/odoo/enterprise",
  "$autoDetectAddons",
]
​
addons_merge
merge | override
default:"merge"
Controls how addons_paths is combined with the parent profile when using extends.
  • "merge" — append the parent’s addon paths to the child’s list.
  • "override" — use only the child’s addon paths, ignoring the parent’s.
​
python_path
string
default:"system python"
Path to the Python executable (or command name resolvable on $PATH) to use for type analysis. OdooLS uses this to discover installed packages and stubs.
python_path = "/home/user/.venv/bin/python"
​
stdlib
string
Alternative path to Python standard library stubs. When not set, OdooLS uses its bundled typeshed stdlib stubs.
stdlib = "/opt/custom-stubs/stdlib"
​
additional_stubs
string[]
List of additional directories containing type stubs. Each stub package must be in a subdirectory named after the package it stubs.
additional_stubs = ["/opt/stubs/mypackage-stubs"]
​
additional_stubs_merge
merge | override
default:"merge"
Controls how additional_stubs is combined with the parent profile when using extends.
  • "merge" — append the parent’s stubs to the child’s list.
  • "override" — use only the child’s stubs, ignoring the parent’s.

​
Performance

​
file_cache
boolean
default:"true"
Enable on-disk caching of parsed files to speed up startup. Disable if you encounter stale analysis results.
file_cache = false
​
auto_refresh_delay
integer
default:"1000"
Delay in milliseconds before OdooLS refreshes diagnostics after a file change. Must be between 1000 and 15000 ms. Values outside this range are clamped automatically.
auto_refresh_delay = 2000

​
Diagnostics

​
diag_missing_imports
none | only_odoo | all
default:"all"
Controls which missing-import diagnostics are reported.
ValueBehaviour
"none"Suppresses all missing-import warnings
"only_odoo"Reports missing imports only within the Odoo source tree
"all"Reports all missing imports (default)
diag_missing_imports = "only_odoo"
​
diagnostic_settings
map
Per-code severity overrides. Keys are diagnostic codes (OLS01000, OLS03001, …). Valid severity values: "Error", "Warning", "Info", "Hint", "Disabled".
[config.diagnostic_settings]
OLS03001 = "Disabled"
OLS02001 = "Warning"
diagnostic_settings uses TOML standard table syntax ([config.diagnostic_settings]), not an array-of-tables header. Place it after the [[config]] block it belongs to.
​
diagnostic_filters
object[]
Ordered list of filter rules. Each rule can suppress or restrict diagnostics by path, code, or severity type. A diagnostic is suppressed when it matches a rule with path_type = "in" (the default) and at least one of the rule’s patterns applies.Each filter object has the following fields:
FieldTypeDescription
pathsstring[]Glob patterns matched against the file path
codesstring[]Regular expressions matched against the diagnostic code
typesstring[]Severity levels to match ("Error", "Warning", "Info", "Hint")
path_type"in" | "not_in""in" suppresses matching diagnostics; "not_in" suppresses diagnostics outside the matched paths
All filter arrays default to [] (match everything if left empty). "Disabled" is not a valid value for types.
[[config]]
name = "default"
odoo_path = "/opt/odoo/17.0"

[[config.diagnostic_filters]]
paths   = ["/opt/odoo/custom_addons/my_module/**"]
codes   = ["OLS03.*"]
types   = ["Warning"]
path_type = "in"

​
Autocomplete

​
ac_filter_model_names
boolean
default:"true"
When true, autocomplete suggestions for model references are filtered to valid model names only. Set to false to see all symbols in completion lists.
ac_filter_model_names = false

​
Stubs

​
no_typeshed_stubs
boolean
default:"false"
Disable the bundled typeshed stubs for external packages. This does not remove the standard library stubs (those are always required). Use this when you want to provide your own versions of third-party package stubs via additional_stubs.
no_typeshed_stubs = true

​
Variables

​
$version
string
Sets a version string that can be referenced as $version in other path fields.Accepted values:
  • A version string such as "17.0" — used as-is.
  • A path to a __manifest__.py file — OdooLS reads the "version" key and extracts the major.minor components.
  • A path ending with ${splitVersion} — OdooLS enumerates versioned subdirectories at that path and creates one derived profile per version found.
# Point to a manifest to auto-detect version
$version = "/opt/odoo/custom_addons/my_module/__manifest__.py"
​
$base
string
Sets a base path variable that can be referenced as $base in other path fields.Supports the special suffix ${detectVersion}: OdooLS matches the workspace path against the prefix before ${detectVersion} and extracts the next path component as the version, setting $version automatically.
# Detect version from workspace path automatically
$base = "/opt/odoo/${detectVersion}"
odoo_path = "$base"
addons_paths = ["$base/addons"]
See Configuration Profiles for a full auto-detection example.

​
Complete example

[[config]]
name = "default"
odoo_path = "/opt/odoo/17.0"
addons_paths = ["/opt/odoo/custom_addons", "$autoDetectAddons"]
python_path = "python3"
diag_missing_imports = "only_odoo"
auto_refresh_delay = 500
file_cache = true

[config.diagnostic_settings]
OLS03001 = "Disabled"
OLS02001 = "Warning"

[[config.diagnostic_filters]]
paths     = ["/opt/odoo/custom_addons/legacy_module/**"]
codes     = ["OLS03.*"]
types     = ["Warning"]
path_type = "in"

Build docs developers (and LLMs) love

Get started for freeTalk to us