Settings Management
Load configuration from environment with pydantic-settings.
Recipe
Quick-reference recipe card - copy-paste ready.
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
database_url: str
debug: bool = FalseWhen to reach for this:
- 12-factor config
- Typed env vars
- Secret separation
Working Example
class Settings(BaseSettings):
model_config = SettingsConfigDict(env_file=".env", env_prefix="APP_")What this demonstrates:
- env_file support
- env_prefix
- SettingsConfigDict
Deep Dive
How It Works
- Settings read env on instantiation.
- Use secrets files or vault sidecars in prod.
- Never commit .env with real credentials.
Gotchas
- Boundary validation skipped - Invalid data reaches persistence layers.. Fix: Validate with Pydantic or framework forms at the edge..
- Leaking stack traces - Clients see internal errors.. Fix: Map exceptions to stable HTTP responses..
- Blocking async event loops - Workers stall under concurrent load.. Fix: Use async drivers or threadpool wrappers..
- Secrets in source control - Credentials leak via git history.. Fix: Load secrets from env or a vault at runtime..
- Missing observability - Incidents are hard to debug.. Fix: Add structured logs, metrics, and request IDs..
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| Alternate framework in this cookbook | Team standard or existing monolith | Greenfield API with different constraints |
| Managed BaaS | CRUD-only MVP | Custom auth, workflows, or compliance needs |
| gRPC | Internal high-performance RPC | Public HTTP clients and browser access |
FAQs
When should I adopt pydantic-settings?
Use it when the patterns and trade-offs on this page match your API or data boundary.
What is the top production mistake with pydantic-settings?
Skipping validation, timeouts, or explicit error contracts at the HTTP edge.
How do I test pydantic-settings?
Use the framework test client, override dependencies, and assert status plus JSON shape.
Does pydantic-settings work with Python 3.14?
Yes - examples target Python 3.14 with pinned framework versions from the stack footer.
How does pydantic-settings relate to Pydantic 2?
Validate and serialize at boundaries; keep services working with typed domain objects.
Sync or async?
Prefer async routes when I/O dominates; keep CPU work small or offload to workers.
Where should business logic live?
Thin handlers; services own rules; repositories own queries.
How do I document APIs?
Publish OpenAPI or schema docs that match response models in code.
How do I handle versioning?
Explicit URL or header versioning with deprecation windows - avoid silent breaks.
What should I read next?
Follow the Related links for the next layer of depth in this section.
How do I stay secure?
Authenticate callers, authorize per resource, rate-limit, and never log secrets.
Performance first step?
Measure DB and upstream latency before swapping frameworks.
Related
- Pydantic Basics - Core models
- Validators - Custom rules
- Serialization - model_dump
- Settings Management - env config
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+.