Configuration & Settings

Configuration loads from the environment at startup, validates once with Pydantic 2, and keeps secrets out of source control so the same artifact runs in dev, staging, and production.

Recipe

Quick-reference recipe card - copy-paste ready.

from pydantic import Field
from pydantic_settings import BaseSettings, SettingsConfigDict
 
class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
 
    app_name: str = "billing-api"
    database_url: str = Field(alias="DATABASE_URL")
    debug: bool = False
 
settings = Settings()

When to reach for this:

• Deploying the same container image across environments
• Preventing "works locally" from missing required env vars
• Centralizing timeouts, feature flags, and service URLs
• Auditing which settings exist without reading scattered os.getenv calls

Working Example

# settings.py
from functools import lru_cache
from typing import Literal
 
from pydantic import Field, PostgresDsn, field_validator
from pydantic_settings import BaseSettings, SettingsConfigDict
 
class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        extra="ignore",
    )
 
    environment: Literal["local", "staging", "production"] = "local"
    app_name: str = "orders-api"
    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO"
    database_url: PostgresDsn
    redis_url: str = "redis://localhost:6379/0"
    secret_key: str = Field(min_length=32)
    http_timeout_seconds: float = 5.0
 
    @field_validator("secret_key")
    @classmethod
    def forbid_placeholder_secret(cls, value: str) -> str:
        if value in {"changeme", "replace-me"}:
            raise ValueError("SECRET_KEY must be set to a real value")
        return value
 
@lru_cache
def get_settings() -> Settings:
    return Settings()
 
# main wiring
import logging
 
def configure_logging(settings: Settings) -> None:
    logging.basicConfig(level=settings.log_level)
 
def build_app():
    settings = get_settings()
    configure_logging(settings)
    # pass settings.database_url into repository factory
    return settings
 
if __name__ == "__main__":
    s = build_app()
    print(f"{s.app_name} ready in {s.environment}")

# .env.example (committed - no secrets)
DATABASE_URL=postgresql://user:pass@localhost:5432/orders
SECRET_KEY=generate-a-32-char-random-string-for-local-dev
ENVIRONMENT=local
LOG_LEVEL=DEBUG

What this demonstrates:

• Required secrets fail fast at import/startup with clear validation errors
• .env supports local dev; production relies on real environment variables
• get_settings() cached so parsing happens once per process
• extra="ignore" prevents typos from silently creating attributes

Deep Dive

How It Works

• Pydantic Settings reads env vars (and optional .env) into typed fields
• Field aliases map DATABASE_URL env name to database_url attribute
• Validators enforce business rules beyond type coercion
• Composition root calls get_settings() and passes values into adapters

12-Factor Checklist

Python Notes

# Nested settings for subsystems
from pydantic_settings import BaseSettings
 
class S3Settings(BaseSettings):
    model_config = SettingsConfigDict(env_prefix="S3_")
    bucket: str
    region: str = "us-east-1"
 
class Settings(BaseSettings):
    s3: S3Settings = S3Settings()

Gotchas

• Committing .env with secrets - keys leak via git history. Fix: commit .env.example only; block .env in .gitignore.
• Reading env vars at import time everywhere - untestable modules and hidden order dependencies. Fix: one settings module; inject into factories.
• No validation on URLs - bad DSN fails deep in SQLAlchemy. Fix: PostgresDsn, RedisDsn, or custom validators at startup.
• Boolean env surprises - "false" string is truthy in naive if os.getenv("X"). Fix: Pydantic bool parsing handles 0, false, no.
• Mutable settings singleton - code mutates settings.debug = True at runtime. Fix: treat settings as immutable after load; use frozen=True models where practical.
• Mixing Django settings with pydantic-settings - two sources of truth. Fix: pick one pattern per app; bridge only at the composition root.

Alternatives

FAQs

Related

• Dependency Injection & Wiring - injecting settings at the root
• Project Architecture Decision Checklist - config decisions up front
• Codebase Audit Checklist - secret and config red flags
• Dependency & Environment Conflicts - env mismatch debugging
• Architecture Best Practices - configuration habits

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.