Pydantic Settings

2.13.1 · active · verified Tue Mar 24

Settings management using Pydantic. Provides BaseSettings for loading config from environment variables, .env files, and secrets files with full type validation. Extracted from pydantic core into a separate package in V2. Current version is 2.13.1 (Feb 2026).

Warnings

breaking 'from pydantic import BaseSettings' raises ImportError in pydantic V2. BaseSettings moved to separate pydantic-settings package.
Fix: pip install pydantic-settings; from pydantic_settings import BaseSettings
gotcha If env_file path does not exist, pydantic-settings silently ignores it with no error. Fields fall back to environment variables or defaults. Wrong .env path causes silent misconfiguration.
Fix: Verify .env file exists before startup or use extra='forbid' to catch missing required fields early.
gotcha Environment variables take precedence over .env file values. If the same variable is set in both the shell environment and .env, the shell value wins.
Fix: Expected behavior — documented priority order: init args > env vars > .env file > defaults.
gotcha env_file in 2.13.x has a regression where .env files are not loaded when using CliApp.run() without debugger attached. Known issue, tracked in pydantic-settings #795.
Fix: Pass _env_file='.env' directly to CliApp.run(Settings, _env_file='.env') as workaround, or pin to 2.12.0.
gotcha Nested settings via env_nested_delimiter require sub-models to inherit from pydantic.BaseModel, not BaseSettings.
Fix: class SubModel(BaseModel): ... — not BaseSettings.
gotcha Inner class Config: is V1 style and deprecated. Use model_config = SettingsConfigDict(...) at class level.
Fix: model_config = SettingsConfigDict(env_file='.env')
deprecated Passing settings config as constructor underscore kwargs (_env_file, _env_prefix) is deprecated. Use model_config = SettingsConfigDict(...) instead.
Fix: model_config = SettingsConfigDict(env_file='.env', env_prefix='APP_')

Install

pip install pydantic-settings Python
pip install 'pydantic-settings[toml]' Python (with TOML file support)
pip install 'pydantic-settings[yaml]' Python (with YAML file support)

Imports

BaseSettings

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file='.env', env_file_encoding='utf-8')

    api_key: str
    debug: bool = False

settings = Settings()

BaseSettings was removed from pydantic core in V2. 'from pydantic import BaseSettings' raises ImportError. Must install pydantic-settings separately and import from pydantic_settings.

SettingsConfigDict

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file='.env',
        env_prefix='APP_',
        case_sensitive=False
    )
    api_key: str

Inner Config class is pydantic V1 style. Use model_config = SettingsConfigDict(...) in V2.

Quickstart

Minimal BaseSettings loading from .env file with pydantic-settings 2.x.

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file='.env',
        env_file_encoding='utf-8',
        extra='ignore'  # ignore unknown env vars
    )

    api_key: str
    debug: bool = False
    port: int = 8000

# reads from env vars and .env file
settings = Settings()
print(settings.api_key)

view raw JSON →