pydantic-settings

Pydantic Settings extends Pydantic’s BaseModel into BaseSettings, a class that automatically reads and validates configuration values from environment variables, .env files, JSON, YAML, TOML, Docker/Kubernetes secrets files, cloud secret managers, and CLI arguments — in a configurable precedence order. Every setting is a typed, validated Pydantic field, so misconfigured environments fail fast at startup with clear error messages instead of surfacing as runtime bugs deep in application code.

Maintained by the Pydantic core team as an official companion package, it is the de facto standard for twelve-factor-app configuration in the Python ecosystem, used across FastAPI services, Django projects, CLI tools, and background workers to centralize environment-driven config into a single validated, IDE-autocompletable class.

What You Get

• BaseSettings base class that behaves like a normal Pydantic model but auto-populates fields from environment variables and other sources on instantiation
• Built-in source providers for .env files, JSON, YAML, TOML, pyproject.toml, Docker/Kubernetes-style secrets directories, and CLI argument parsing
• First-party cloud secret manager integrations for AWS Secrets Manager, Azure Key Vault, and GCP Secret Manager via optional extras
• Configurable source precedence (init kwargs > env vars > dotenv > file secrets > defaults, fully overridable) and nested-delimiter support for structured env vars like SUB__FIELD=value
• A full CLI-parsing source (cli_parse_args) that turns any BaseSettings model into an argparse-style command-line interface with kebab-case flags, subcommands, and auto-generated help text
• AliasChoices and env_prefix support for reading the same field from multiple differently-named environment variables

Common Use Cases

• Centralizing FastAPI/Django/Flask app configuration (database URLs, API keys, feature flags) into one validated, autocompletable settings object
• Twelve-factor-app deployments where config must be injected via environment variables in Docker/Kubernetes without code changes
• Building typed CLI tools where flags, env vars, and config files all need to resolve into the same validated model
• Pulling secrets from AWS Secrets Manager, Azure Key Vault, or GCP Secret Manager at startup without hand-rolled SDK calls
• Multi-environment configuration (dev/staging/prod) where different .env files or config layers override a shared set of defaults

Under The Hood

Architecture Configuration resolution flows through a pipeline of PydanticBaseSettingsSource objects assembled in BaseSettings._settings_init_sources (pydantic_settings/main.py): init kwargs, CLI args, environment variables, dotenv files, file secrets, and any user-supplied sources are each wrapped as a source instance, called in a configurable precedence order, and their resulting dicts are deep-merged via Pydantic’s deep_update before being handed to the model constructor for validation — so every value, regardless of origin, passes through the same Pydantic validation path as a normal BaseModel field.

Tech Stack The package is pure Python (99.9% per GitHub’s language breakdown) targeting 3.10-3.14, built on pydantic>=2.7 for the validation core, python-dotenv for .env parsing, and typing-inspection for runtime generic/alias introspection; optional extras (pyyaml, tomli, azure-keyvault-secrets+azure-identity, boto3, google-cloud-secret-manager) are pulled in only when their respective source providers are used, keeping the base install lightweight. Packaging uses hatchling with hatch.version reading the version from pydantic_settings/version.py.

Code Quality Source logic is factored into one file per provider under pydantic_settings/sources/providers/ (env, dotenv, json, yaml, toml, pyproject, secrets, nested_secrets, cli, aws, azure, gcp), sharing common field-resolution and alias-handling helpers in sources/base.py and sources/utils.py — a clean separation that makes each source independently testable. The test suite spans 12,000+ lines across per-provider test files (test_source_cli.py, test_source_aws_secrets_manager.py, etc.) plus dedicated precedence/merging and docs-example tests, and the codebase is typed throughout with a py.typed marker, run under strict mypy and ruff via pre-commit hooks.

API Design The core API surface is a single subclassing pattern (class Settings(BaseSettings): ...) that developers already know from Pydantic’s BaseModel, so the learning curve for basic usage is close to zero for anyone using Pydantic elsewhere; configuration of behavior (env prefix, nested delimiter, secrets dir, CLI parsing) is done declaratively via SettingsConfigDict, keeping field declarations free of source-specific noise, though the surface grows large once CLI parsing and multiple file sources are combined — the docs run to 3,400+ lines covering the full option matrix.