pydantic-settings

You can change the order of priority or add/remove settings sources by overriding the settings_customise_sources class method in your Settings class.

settings_customise_sources receives four arguments representing the built-in sources: init_settings, env_settings, dotenv_settings, and file_secret_settings. It must return a tuple of callables. The order of the returned tuple determines priority: the first item has the highest priority.

Changing Priority

To make environment variables override __init__ arguments, return env_settings before init_settings in the tuple.

Adding Sources

To add a custom source, implement a class inheriting from PydanticBaseSettingsSource and include it in the returned tuple from settings_customise_sources.

from pydantic import PostgresDsn
from pydantic_settings import BaseSettings, PydanticBaseSettingsSource

class Settings(BaseSettings):
    database_dsn: PostgresDsn

    @classmethod
    def settings_customise_sources(
        cls,
        settings_cls: type[BaseSettings],
        init_settings: PydanticBaseSettingsSource,
        env_settings: PydanticBaseSettingsSource,
        dotenv_settings: PydanticBaseSettingsSource,
        file_secret_settings: PydanticBaseSettingsSource,
    ) -> tuple[PydanticBaseSettingsSource, ...]:
        # env_settings now has higher priority than init_settings
        return env_settings, init_settings, file_secret_settings

By default, if extra='forbid' is set in model_config, any entry in your .env file that does not correspond to a defined field in your BaseSettings model will raise a ValidationError.

You can control this behavior using the dotenv_filtering setting in SettingsConfigDict:

• 'match_prefix': Only variables matching the env_prefix will be passed to the model. This is useful for scoping a single .env file to a specific model.
• 'only_existing': Only variables that have a corresponding field in the model will be passed. This makes the dotenv source behave like standard environment variables.

Note on env_prefix asymmetry: If you have an env_prefix set (e.g., app_), an unprefixed entry in the .env file that matches a field name (e.g., debug=true for a field debug) is silently ignored rather than being treated as an extra field. However, a completely unrelated unprefixed entry (e.g., foo=bar) will still raise a ValidationError if extra='forbid' is active.

from pydantic_settings import BaseSettings, SettingsConfigDict

# Example of using dotenv_filtering to avoid ValidationErrors from extra keys
class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file='.env',
        dotenv_filtering='only_existing'
    )

If you want to avoid the requirement for valid JSON in environment variables, you have three options:

1. Per-field: Annotate a field with NoDecode. This disables JSON decoding for that specific field, allowing you to use a field_validator (with mode='before') to parse the raw string (e.g., comma-separated values).
2. Global: Set enable_decoding=False in SettingsConfigDict to disable JSON parsing for all fields.
3. Force JSON: If global decoding is disabled, you can force JSON parsing for a specific field using the ForceDecode annotation.

from typing import Annotated
from pydantic import field_validator
from pydantic_settings import BaseSettings, NoDecode

class Settings(BaseSettings):
    # Disables JSON parsing; use validator to handle '1,2,3'
    numbers: Annotated[list[int], NoDecode]

    @field_validator('numbers', mode='before')
    @classmethod
    def decode_numbers(cls, v: str) -> list[int]:
        return [int(x) for x in v.split(',')]

You can load configuration from files using specialized settings sources. The available sources are:

• JsonConfigSettingsSource: Requires json_file and json_file_encoding.
• PyprojectTomlConfigSettingsSource: Requires pyproject_toml_depth (optional) and pyproject_toml_table_header (optional).
• TomlConfigSettingsSource: Requires toml_file and toml_table_header (optional).
• YamlConfigSettingsSource: Requires yaml_file and yaml_file_encoding.

To use these, override the settings_customise_sources class method in your BaseSettings subclass and return the desired source(s).

from pydantic_settings import (
    BaseSettings,
    PydanticBaseSettingsSource,
    SettingsConfigDict,
    TomlConfigSettingsSource,
)

class Settings(BaseSettings):
    foobar: str
    model_config = SettingsConfigDict(toml_file='config.toml')

    @classmethod
    def settings_customise_sources(
        cls, 
        settings_cls: type[BaseSettings], 
        init_settings: PydanticBaseSettingsSource, 
        env_settings: PydanticBaseSettingsSource, 
        dotenv_settings: PydanticBaseSettingsSource, 
        file_secret_settings: PydanticBaseSettingsSource
    ) -> tuple[PydanticBaseSettingsSource, ...]:
        return (TomlConfigSettingsSource(settings_cls),)

Pydantic settings supports multiple styles for parsing complex types from the CLI:

Lists support:

• JSON style: --field='[1,2]'
• Argparse style: --field 1 --field 2
• Lazy style: --field=1,2

Dictionaries support:

• JSON style: --field='{"k1": 1, "k2": 2}'
• Environment variable style: --field k1=1 --field k2=2

You can mix these styles (e.g., using lazy list style and JSON dictionary style in the same command).

import sys
from pydantic_settings import BaseSettings

class Settings(BaseSettings, cli_parse_args=True):
    my_list: list[int]
    my_dict: dict[str, int]

# List examples
sys.argv = ['example.py', '--my_list', '[1,2]']
sys.argv = ['example.py', '--my_list', '1', '--my_list', '2']
sys.argv = ['example.py', '--my_list', '1,2']

# Dictionary examples
sys.argv = ['example.py', '--my_dict', '{"k1":1,"k2":2}']
sys.argv = ['example.py', '--my_dict', 'k1=1', '--my_dict', 'k2=2']