Pydantic Settings

2.13.1 verified Tue May 12 auth: no python install: verified quickstart: verified

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).

pip install pydantic-settings

Common errors

error PydanticImportError: `BaseSettings` has been moved to the `pydantic-settings` package. ↓

cause This error occurs because in Pydantic v2, `BaseSettings` was moved from the main `pydantic` package to a new, separate package called `pydantic-settings`.

fix

First, install the pydantic-settings package: pip install pydantic-settings. Then, change your import statement from from pydantic import BaseSettings to from pydantic_settings import BaseSettings.

error ModuleNotFoundError: No module named 'pydantic_settings' ↓

cause This error indicates that the `pydantic-settings` library has not been installed in your current Python environment.

fix

Install the pydantic-settings package using pip: pip install pydantic-settings.

error pydantic_core._pydantic_core.ValidationError: 1 validation error for Settings\nfield_name\n Field required [type=missing, input_value={}, input_type=dict] ↓

cause This validation error typically means that a required field in your `BaseSettings` model is not receiving a value, often because the associated environment variable or `.env` file entry is missing or the `.env` file is not being loaded correctly.

fix

Ensure that the required environment variable is set or correctly defined in your .env file. If using a .env file, specify its path explicitly in model_config (e.g., model_config = SettingsConfigDict(env_file='.env')) and provide an absolute path if your script is run from a different directory than the .env file (e.g., env_file=os.path.join(os.path.dirname(__file__), '.env')).

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[toml]'

pip install 'pydantic-settings[yaml]'

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) toml - - 0.45s 28.5M

3.10 alpine (musl) yaml - - 0.45s 30.6M

3.10 alpine (musl) pydantic-settings - - 0.46s 28.4M

3.10 slim (glibc) toml - - 0.31s 28M

3.10 slim (glibc) yaml - - 0.32s 31M

3.10 slim (glibc) pydantic-settings - - 0.32s 28M

3.11 alpine (musl) toml - - 0.72s 31.9M

3.11 alpine (musl) yaml - - 0.69s 33.5M

3.11 alpine (musl) pydantic-settings - - 0.69s 31.1M

3.11 slim (glibc) toml - - 0.56s 32M

3.11 slim (glibc) yaml - - 0.55s 34M

3.11 slim (glibc) pydantic-settings - - 0.56s 31M

3.12 alpine (musl) toml - - 0.83s 23.5M

3.12 alpine (musl) yaml - - 0.81s 25.1M

3.12 alpine (musl) pydantic-settings - - 0.79s 22.8M

3.12 slim (glibc) toml - - 0.80s 23M

3.12 slim (glibc) yaml - - 0.76s 26M

3.12 slim (glibc) pydantic-settings - - 0.77s 22M

3.13 alpine (musl) toml - - 0.74s 23.2M

3.13 alpine (musl) yaml - - 0.76s 24.8M

3.13 alpine (musl) pydantic-settings - - 0.73s 22.4M

3.13 slim (glibc) toml - - 0.70s 23M

3.13 slim (glibc) yaml - - 0.70s 25M

3.13 slim (glibc) pydantic-settings - - 0.70s 22M

3.9 alpine (musl) toml - - 0.39s 27.9M

3.9 alpine (musl) yaml - - 0.39s 30.0M

3.9 alpine (musl) pydantic-settings - - 0.41s 27.8M

3.9 slim (glibc) toml - - 0.38s 28M

3.9 slim (glibc) yaml - - 0.36s 30M

3.9 slim (glibc) pydantic-settings - - 0.36s 27M

Imports

BaseSettings

wrong

from pydantic import BaseSettings

correct

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

wrong

class Settings(BaseSettings):
    class Config:
        env_file = '.env'
        env_prefix = 'APP_'

correct

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 verified last tested: 2026-05-12

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)