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. SecretStr-typed fields should be placed in a separate secrets file with the same name but suffixed with .secrets (e.g. settings.secrets.toml) and must have permissions set to 0600. Non-secret fields will be ignored if found in the secrets file, and secret fields will be rejected if found in the main settings file, to encourage proper separation of concerns.

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. Secret values from the .secrets.(toml|yaml) file

3. Non-secret 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)

• 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 S3-compatible 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 utils: UtilsConfig [Optional]

Miscellaneous anemoi-utils settings.

Object storage – [object-storage]

pydantic model anemoi.utils.settings_schema.object_storage.ObjectStorageConfig

Object storage configuration for S3-compatible services.

Fields:

• access_key_id (pydantic.types.SecretStr | None)

• endpoint_url (str | None)

• secret_access_key (pydantic.types.SecretStr | None)

• type (str)

field type: str = 's3'

Default storage type (only ‘s3’ is currently supported).

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

Global endpoint URL (leave empty for default AWS endpoint).

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

Global access key ID.

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

Global secret access key.

pydantic model anemoi.utils.settings_schema.object_storage.ObjectStorageBucketConfig

Per-bucket overrides for object storage configuration.

Fields:

• access_key_id (pydantic.types.SecretStr | None)

• endpoint_url (str | None)

• region (str | None)

• secret_access_key (pydantic.types.SecretStr | None)

• skip_signature (bool | None)

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

Bucket-specific endpoint URL.

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

Bucket-specific access key ID.

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

Bucket-specific secret access key.

field region: str | None = None

Bucket-specific region.

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

Skip signature for public buckets.

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.