Settings

Anemoi uses pydantic-settings to manage configuration. Every setting can be configured via a TOML/YAML config file or overridden at runtime with an environment variable.

Configuration files

File	Purpose
~/.config/anemoi/settings.toml	Main configuration (non-secret values)
~/.config/anemoi/settings.yaml	Alternative YAML format for main configuration
~/.config/anemoi/settings.secrets.toml	Secret values (must be mode 0600)
~/.config/anemoi/settings.secrets.yaml	Alternative YAML format for secrets

Override the file location by setting the ANEMOI_SETTINGS_FILE environment variable.

Loading priority

Settings are loaded with the following priority (highest first):

1. Environment variables (ANEMOI_SETTINGS_*)

2. Secrets file (settings.secrets.toml / settings.secrets.yaml)

3. Main config file (settings.toml / settings.yaml)

4. Default values defined in the schema

Environment variables

All settings can be overridden using environment variables. The naming convention is:

ANEMOI_SETTINGS_<SECTION>__<KEY>=<value>

Sections and keys are upper-cased, underscores in field names stay as single underscores, and nested sections use double underscores (__) as separators.

Examples

Object storage endpoint

The TOML key endpoint-url in section [object-storage] maps to field name endpoint_url on ObjectStorageConfig. The environment variable is built as ANEMOI_SETTINGS_ + OBJECT_STORAGE + __ + ENDPOINT_URL:

# Set the global S3 endpoint
export ANEMOI_SETTINGS_OBJECT_STORAGE__ENDPOINT_URL="https://s3.example.com"

Object storage credentials (secrets)

Secret fields follow the same naming. The field access_key_id on ObjectStorageConfig becomes:

# Override the S3 access key at runtime
export ANEMOI_SETTINGS_OBJECT_STORAGE__ACCESS_KEY_ID="AKIA..."
export ANEMOI_SETTINGS_OBJECT_STORAGE__SECRET_ACCESS_KEY="wJalr..."

Note

For persistent secret storage, prefer the settings.secrets.toml file (mode 0600) over environment variables to avoid secrets leaking into process listings or shell history.

Dataset search paths

List fields are set as JSON-encoded arrays:

# Add dataset search paths
export ANEMOI_SETTINGS_DATASETS__PATH='["/data/zarr", "s3://bucket/datasets"]'

Boolean flags

# Skip dataset naming convention checks
export ANEMOI_SETTINGS_DATASETS__IGNORE_NAMING_CONVENTIONS="true"

# Use search-path fallback when a .zarr path is not found
export ANEMOI_SETTINGS_DATASETS__USE_SEARCH_PATH_NOT_FOUND="true"

ParamDB settings

# Change the default GRIB parameter origin
export ANEMOI_SETTINGS_PARAMDB__DEFAULT_ORIGIN="ecmf"

# Extend the parameter cache lifetime to 90 days
export ANEMOI_SETTINGS_PARAMDB__CACHE_LENGTH="90"

Utils – custom grids directory

export ANEMOI_SETTINGS_UTILS__GRIDS_PATH="~/my-grids"

Custom settings file location

This is a standalone variable (not part of the nested schema) that controls which configuration file is loaded:

# Load settings from a project-specific file instead of the default
export ANEMOI_SETTINGS_FILE="/project/config/anemoi-settings.toml"

Slurm / batch job usage

Environment variables are particularly useful in batch jobs where you cannot modify config files on shared filesystems:

#!/bin/bash
#SBATCH --job-name=anemoi-train

export ANEMOI_SETTINGS_OBJECT_STORAGE__ENDPOINT_URL="https://s3.internal.hpc"
export ANEMOI_SETTINGS_DATASETS__PATH='["/scratch/datasets"]'
export ANEMOI_SETTINGS_PARAMDB__CACHE_LENGTH="7"

srun python -m anemoi.training ...

Settings schema reference

The reference below is auto-generated from the Pydantic schema.

AnemoiSettings

pydantic settings anemoi.utils.settings.AnemoiSettings

Settings for Anemoi.

Use the ANEMOI_SETTINGS_FILE environment variable to specify a custom location for the main settings file (default: ~/.config/anemoi/settings.toml).

The main settings file can be in either TOML or YAML format; the extension is ignored. Keys may be placed in any settings file, secret or not: there is no requirement to partition secret and non-secret keys into separate files. The only rule is that any file containing a ``SecretStr`` value must have permissions ``0600``; a secret found in a file that is readable by group or others is a fatal error (PermissionError).

An optional secrets file with the same name but suffixed with .secrets (e.g. settings.secrets.toml) is also read. It is the natural place to keep secrets when the main settings file must stay readable by others.

Note: Init kwargs are intentionally disabled as a source of settings.

Settings are loaded with the following priority (highest to lowest):

1. Environment variables (with prefix ANEMOI_SETTINGS_ and keys in upper case with underscores)

2. Values from the .secrets.(toml|yaml) file

3. Values from the .(toml|yaml) file

4. Default values defined in the AnemoiSettings class and its nested models

Fields:

• datasets (anemoi.utils.settings_schema.datasets.DatasetsConfig)

• nexus (anemoi.utils.settings_schema.nexus.NexusConfig)

• object_storage (anemoi.utils.settings_schema.object_storage.ObjectStorageConfig)

• paramdb (anemoi.utils.settings_schema.paramdb.ParamDBConfig)

• registry (anemoi.utils.settings_schema.registry.RegistryConfig)

• utils (anemoi.utils.settings_schema.utils.UtilsConfig)

field object_storage: ObjectStorageConfig [Optional] (alias 'object-storage')

Configuration for cloud (S3-compatible and Azure Blob) object storage.

field datasets: DatasetsConfig [Optional]

Dataset discovery and validation settings.

field paramdb: ParamDBConfig [Optional]

GRIB parameter database lookup settings.

field registry: RegistryConfig [Optional]

Configuration for access to the Anemoi registry.

field nexus: NexusConfig [Optional]

Configuration for access to the Anemoi Nexus.

field utils: UtilsConfig [Optional]

Miscellaneous anemoi-utils settings.

Object storage – [object-storage]

pydantic model anemoi.utils.settings_schema.object_storage.ObjectStorageConfig

Top-level, global object storage configuration.

Inherits all backend fields from ObjectStorageBucketConfig used for per-bucket/account overrides under __pydantic_extra__ (named sub-sections, e.g. [object-storage.”my-bucket”]).

Fields:

• access_key_id ()

• account_key ()

• account_name ()

• endpoint_url ()

• region ()

• sas_token ()

• secret_access_key ()

• skip_signature ()

• type (Literal['s3', 'az'] | None)

field endpoint_url: str | None = None (alias 'endpoint-url')

Endpoint URL. S3-compatible services, Azurite or sovereign clouds for Azure.

field skip_signature: bool | None = False (alias 'skip-signature')

Skip signature for public storage.

field access_key_id: SecretStr | None = None (alias 'access-key-id')

S3 bucket access key ID.

field secret_access_key: SecretStr | None = None (alias 'secret-access-key')

S3 bucket secret access key.

field region: str | None = None

S3 bucket region.

field account_name: SecretStr | None = None (alias 'account-name')

Azure Blob Storage account name.

field account_key: SecretStr | None = None (alias 'account-key')

Azure Blob Storage account key.

field sas_token: SecretStr | None = None (alias 'sas-token')

Azure Blob Storage SAS token. May include or omit the leading ‘?’.

field type: Literal['s3', 'az'] | None = None

Deprecated: retained for backwards compatibility. Backends are dispatched by URL scheme (s3://, abfs://).

pydantic model anemoi.utils.settings_schema.object_storage.ObjectStorageBucketConfig

Object storage configuration for S3-compatible and Azure Blob services.

At the top level (ObjectStorageConfig) these fields act as global defaults. Under a named sub-section (e.g. [object-storage.”my-bucket”]) they act as per-bucket/account overrides.

Fields:

• access_key_id (pydantic.types.SecretStr | None)

• account_key (pydantic.types.SecretStr | None)

• account_name (pydantic.types.SecretStr | None)

• endpoint_url (str | None)

• region (str | None)

• sas_token (pydantic.types.SecretStr | None)

• secret_access_key (pydantic.types.SecretStr | None)

• skip_signature (bool | None)

field endpoint_url: str | None = None (alias 'endpoint-url')

Endpoint URL. S3-compatible services, Azurite or sovereign clouds for Azure.

field skip_signature: bool | None = False (alias 'skip-signature')

Skip signature for public storage.

field access_key_id: SecretStr | None = None (alias 'access-key-id')

S3 bucket access key ID.

field secret_access_key: SecretStr | None = None (alias 'secret-access-key')

S3 bucket secret access key.

field region: str | None = None

S3 bucket region.

field account_name: SecretStr | None = None (alias 'account-name')

Azure Blob Storage account name.

field account_key: SecretStr | None = None (alias 'account-key')

Azure Blob Storage account key.

field sas_token: SecretStr | None = None (alias 'sas-token')

Azure Blob Storage SAS token. May include or omit the leading ‘?’.

Datasets – [datasets]

pydantic model anemoi.utils.settings_schema.datasets.DatasetsConfig

Configuration for dataset discovery and validation.

Used by anemoi-datasets for search paths, naming convention checks, and named dataset aliases.

Fields:

• ignore_naming_conventions (bool)

• named (anemoi.utils.settings_schema.datasets.DatasetsNamedConfig)

• path (list[str])

• use_search_path_not_found (bool)

field path: list[str] [Optional]

Search paths: list of directories or S3 prefixes for .zarr dataset lookup.

field use_search_path_not_found: bool = False (alias 'use-search-path-not-found')

When true, if a .zarr path does not exist, strip to basename and search the paths above instead of failing immediately.

field ignore_naming_conventions: bool = False (alias 'ignore-naming-conventions')

When true, skip all dataset naming-convention validation during creation.

field named: DatasetsNamedConfig [Optional]

Map of friendly dataset names to full paths or URLs.

pydantic model anemoi.utils.settings_schema.datasets.DatasetsNamedConfig

Named dataset mappings (friendly name -> full path/URL).

ParamDB – [paramdb]

pydantic model anemoi.utils.settings_schema.paramdb.ParamDBConfig

Configuration for the GRIB parameter database lookups.

Used by anemoi.utils.grib to control how GRIB parameter metadata is resolved (online API vs local cache, default origin for disambiguation, and cache lifetime).

Fields:

• cache_length (int)

• default_origin (str)

• local_cache (Annotated[pathlib.Path, pydantic.types.PathType(path_type=file)] | None)

field default_origin: str = 'ecmf' (alias 'default-origin')

Default origin to use when disambiguating parameters with the same shortname.

field cache_length: int = 30 (alias 'cache-length')

Cache length in days for GRIB parameter lookups.

field local_cache: Annotated[Path, PathType(path_type=file)] | None = None (alias 'local-cache')

Path to a local JSON cache file for GRIB parameters. If set, used instead of the online API.

Utils – [utils]

pydantic model anemoi.utils.settings_schema.utils.UtilsConfig

Miscellaneous anemoi-utils settings.

Used by anemoi.utils.grids for custom grid file paths.

Fields:

• cache_directory (pathlib.Path)

• debug_imports_in_cli (bool)

• grids_path (pathlib.Path | None)

field grids_path: Path | None = None (alias 'grids-path')

Custom path to a directory containing precomputed grid files (grid-<name>.npz).

When set, grids are loaded from this directory before falling back to the built-in remote source. Supports ~ expansion.

field cache_directory: Path = PosixPath('/home/docs/.cache/anemoi') (alias 'cache-directory')

Custom path to a directory for caching downloaded files (e.g. grid files or grib param).

field debug_imports_in_cli: bool = False (alias 'debug-imports-in-cli')

Whether to print debug information about imports in the CLI.