What is pydantic-settings and why use it for FastAPI config?
pydantic-settings is a separate package that provides BaseSettings, a Pydantic model that fills its fields from the process environment instead of from a dict you pass in. You install it alongside FastAPI with pip install pydantic-settings. In Pydantic v1, BaseSettings was part of core Pydantic. In v2 it moved into its own package, so from pydantic import BaseSettings from older tutorials will not work on a current install. Pin both pydantic and pydantic-settings in your lockfile, and read the documentation for the version you actually have installed. Configuration options and import paths changed between major versions.
The main benefit is that configuration becomes a typed object you build once at startup. You don't scatter os.getenv calls through the codebase. A Settings subclass declares each value as a typed field:
database_url: strhas no default, so it is required.pool_size: int = 10has a default.debug: bool = Falseis parsed from strings like"true"or"0".
When you instantiate Settings(), Pydantic reads matching environment variables, coerces them to the declared types, and validates them. If DATABASE_URL is unset, the constructor raises ValidationError that names the missing field. If POOL_SIZE=ten, it raises one that names the bad value. Because this happens when the service boots, a misconfigured deployment fails before it serves any traffic. It does not fail on the first request that touches the missing value.
This matters most for backend and platform engineers who run one FastAPI codebase across local, staging, and production. The Settings class is a single, reviewable contract for what each environment must provide.
import os
from pydantic import ValidationError
from pydantic_settings import BaseSettings # v2: separate package, not `from pydantic import BaseSettings`
class Settings(BaseSettings):
database_url: str # no default -> required; read from DATABASE_URL
pool_size: int = 10 # optional; "20" in the env is coerced to int 20
debug: bool = False # "true", "1", "false", "0" are parsed to bool
os.environ.pop("DATABASE_URL", None)
os.environ["POOL_SIZE"] = "ten"
try:
Settings()
except ValidationError as exc:
# The error names both the missing field and the bad value, at boot time.
print(exc)
os.environ["DATABASE_URL"] = "postgresql://app:changeme@localhost:5432/app"
os.environ["POOL_SIZE"] = "20"
os.environ["DEBUG"] = "true"
settings = Settings()
print(settings.pool_size + 1) # 21 -- already an int, no manual casting
print(settings.debug is True) # True
A BaseSettings subclass with required, defaulted and boolean fields. Constructing it against a bad environment raises a ValidationError that names each problem. Constructing it against a valid environment yields a typed config object.
Who should use pydantic-settings?
pydantic-settings fits teams whose FastAPI service is configured by its deployment environment rather than by code:
- Backend engineers running one codebase in several environments. If local, staging, and production differ only in database URLs, feature flags, and credentials, a
Settingsclass keeps those differences in environment variables and secret files. It also documents which values each environment must supply. - Platform and DevOps engineers who deploy containers. Environment variables and mounted secret files are the standard way Docker and Kubernetes hand configuration to a process, and pydantic-settings reads both natively. Validation at boot turns a bad manifest into a failed rollout instead of a runtime incident.
- Teams that already use Pydantic models for request and response bodies. The validation rules, constrained types, and validators are the same ones they already know, so there is little new to learn.
- Services that handle credentials.
SecretStrandsecrets_dirgive a consistent, reviewable way to load and mask secrets.
It is a weaker fit for short scripts that read one or two values, and for systems whose configuration changes while the process is running. The last section covers those cases.
How does pydantic-settings work?
BaseSettings is a subclass of Pydantic's BaseModel. The difference is in what happens before validation. When you call Settings(), the class does not wait for you to pass every field. It first collects candidate values from a list of settings sources:
- Init source: keyword arguments passed to the constructor.
- Environment source: the process environment. For each field, it looks up the variable name derived from the field name,
env_prefix, and the case-sensitivity setting. - Dotenv source: the file named by
env_file, if it exists. - Secrets source: one file per field inside
secrets_dir, if configured.
Each source returns a mapping of field names to raw values. For fields typed as lists, dicts, or nested models, the environment-based sources decode the raw string as JSON, or assemble nested values from env_nested_delimiter variables. The sources are combined in priority order, so a higher source's value for a field replaces a lower one's. Fields that no source supplies fall back to their declared defaults.
The merged values then go through ordinary Pydantic validation: type coercion ("20" becomes 20, "true" becomes True), constrained types such as PositiveInt and PostgresDsn, field validators, and model validators. If anything fails, you get a single ValidationError that lists every problem. If everything passes, you get an ordinary model instance with typed attributes.
Because the sources are an ordered list, the process can be customized. Pydantic-settings v2 lets a subclass override the settings_customise_sources classmethod to reorder, drop, or add sources, for example to make secret files outrank environment variables or to plug in a source that reads from a secret manager. Check the documentation for your installed version before relying on the exact signature.
How does BaseSettings decide where a value comes from?
When you instantiate a BaseSettings subclass, each field is resolved independently. The first source that provides a value wins, and lower sources are never consulted for that field:
Settings(...) kwargs highest priority
│
environment variables
│
dotenv file (env_file)
│
secrets_dir files
│
field defaults lowest priority
Three keys in model_config shape how lookups work:
env_prefix(for example"APP_") namespaces your variables, so a field nameddatabase_urlreadsAPP_DATABASE_URL. This keeps generic names likeDEBUGorPORTfrom colliding with variables set by the base image, the CI runner, or another tool.case_sensitivedefaults toFalse, soapp_debugandAPP_DEBUGboth match. Leave it off unless you need to distinguish between variables that differ only by case.env_filepoints at a dotenv file. If that file is missing, pydantic-settings skips it without raising an error.
Common surprises
Exported shell variables silently override .env. Environment variables rank above the dotenv file. If you once ran export APP_DATABASE_URL=... in your terminal and forgot about it, that value wins over whatever you have edited in .env. No warning is emitted. When a value looks wrong, check env in the same shell before you check the file.
Committed .env files leak credentials. Add .env to .gitignore and commit a .env.example that contains placeholders instead.
.env is a local-development convenience. In production, inject values through real environment variables or mounted secret files. Your orchestrator can manage, rotate, and audit those, which it cannot do for a dotenv file baked into an image.
import os
from pathlib import Path
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
model_config = SettingsConfigDict(
env_prefix="APP_", # field database_url is read from APP_DATABASE_URL
case_sensitive=False, # the default; APP_DEBUG and app_debug both match
env_file=".env", # if the file is missing, it is skipped without an error
)
database_url: str = "sqlite:///./default.db" # lowest priority
debug: bool = False
Path(".env").write_text(
"APP_DATABASE_URL=postgresql://dev:dev-password@localhost:5432/app_dev\n"
"APP_DEBUG=true\n"
)
print(Settings().database_url) # ...app_dev, read from .env
os.environ["APP_DATABASE_URL"] = "postgresql://dev:dev-password@localhost:5432/stale_db"
s = Settings()
print(s.database_url) # ...stale_db: the env var beats .env, with no warning
print(s.debug) # True: each field resolves on its own, so this still comes from .env
print(Settings(database_url="sqlite:///./test.db").database_url) # sqlite:///./test.db
Shows resolution for each field. A value in .env is overridden by an exported environment variable without any warning, and both are overridden by keyword arguments passed to Settings().
How do you model nested config, lists and validation rules?
Group related values into plain BaseModel subclasses, such as DatabaseConfig and RedisConfig, and use them as fields on your top-level settings class. Make the nested classes BaseModel, not BaseSettings, so that only the root class reads the environment. Set env_nested_delimiter="__" in model_config, and DATABASE__HOST populates settings.database.host. Operators can then override one field without restating the whole block.
Fields typed as list, dict or a nested model are parsed as JSON when they come from an environment variable. ALLOWED_ORIGINS='["",""]' becomes a list[str]. A comma-separated string fails to parse unless you write a custom validator.
Tighten the types so bad values fail at load time. Use PostgresDsn and RedisDsn instead of str, PositiveInt for pool sizes and timeouts, and Literal["dev", "staging", "prod"] for the environment name. Field types cannot express rules that span fields. For those, add a model_validator(mode="after") that raises if debug is true while environment == "prod". That error stops the process before it serves traffic with stack traces exposed.
Keep complex values to a minimum, because JSON in environment variables is expensive for operators. Shells consume quotes. YAML in Compose files and Kubernetes manifests reinterprets brackets and colons unless you quote the whole value. A missing quote shows up as a JSON parsing error for that field, which says little about the shell or YAML quoting that caused it. Prefer flat scalar fields with the nested delimiter. Use JSON only for short lists that change rarely.
from typing import Literal
from pydantic import BaseModel, PositiveInt, PostgresDsn, RedisDsn, model_validator
from pydantic_settings import BaseSettings, SettingsConfigDict
class DatabaseConfig(BaseModel):
url: PostgresDsn # DATABASE__URL=postgresql://app:changeme@db:5432/app
pool_size: PositiveInt = 5 # DATABASE__POOL_SIZE=10 overrides just this field
timeout_seconds: PositiveInt = 30
class RedisConfig(BaseModel):
url: RedisDsn # REDIS__URL=redis://cache:6379/0
max_connections: PositiveInt = 10
class Settings(BaseSettings):
# "__" maps DATABASE__POOL_SIZE to settings.database.pool_size
model_config = SettingsConfigDict(env_nested_delimiter="__")
environment: Literal["dev", "staging", "prod"] = "dev"
debug: bool = False
database: DatabaseConfig
redis: RedisConfig
# Parsed as JSON: ALLOWED_ORIGINS='[""]'
# A comma-separated value fails to parse. Keep this list short.
allowed_origins: list[str] = []
# Field types can't express cross-field rules, so check them after parsing.
@model_validator(mode="after")
def reject_debug_in_prod(self) -> "Settings":
if self.debug and self.environment == "prod":
raise ValueError("debug must be false when environment is 'prod'")
return self
settings = Settings()
A settings class with nested database and Redis blocks set through double-underscore variables, a JSON-parsed origins list, constrained DSN, integer and Literal types, and a model validator that rejects debug mode in production.
How should you load secrets with SecretStr and secrets_dir?
Credentials need a type that resists accidental exposure. Declare them as SecretStr and pydantic replaces the value with asterisks in repr(), in str(), and in the default JSON serialization. A settings object that ends up in a log line, a debugger, or a traceback's local variables then shows a mask instead of the password. To read the real value, you call get_secret_value(). That call is easy to search for in code review, so every place the secret is used can be audited.
For the source, set secrets_dir (for example /run/secrets). Pydantic-settings reads one file per field and uses the file name as the field's environment name, including any env_prefix. This matches how Docker secrets and Kubernetes secret volumes deliver credentials. The value stays out of the process environment, where child processes inherit it and anyone with access to /proc/<pid>/environ can read it.
Two limits matter:
- Explicit environment variables override secret files in the default source order. A stale variable will silently win.
SecretStronly masks the wrapper. Once you callget_secret_value(), the plain string can leak through f-strings, exception messages, error response bodies, ormodel_dump()with custom serializers. If the secret came from an environment variable, the masking does nothing to protect it at the OS level.
| Source | Visible in process environment | Typical leak path | Rotation |
|---|---|---|---|
| Environment variables | Yes | Child processes, /proc, crash dumps |
Restart required |
.env file |
Only after loading | Committed to git, baked into images | Edit file and restart |
| Mounted secret files | No | File permissions, volume misconfiguration | Platform updates the file, then restart to reload |
from functools import lru_cache
from fastapi import Depends, FastAPI
from pydantic import SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
# One file per field under /run/secrets (Docker secrets / Kubernetes secret volume).
# File name is the env name, prefix included: /run/secrets/app_db_password
# Note: an APP_DB_PASSWORD env var, if set, overrides the file by default.
model_config = SettingsConfigDict(env_prefix="APP_", secrets_dir="/run/secrets")
db_host: str = "db"
db_user: str = "app"
db_password: SecretStr # masked in repr(), str() and default JSON output
@lru_cache
def get_settings() -> Settings:
return Settings()
def build_dsn(settings: Settings) -> str:
# The single, greppable place the plain value is extracted.
# The returned string is NOT masked: never log it or put it in error responses.
password = settings.db_password.get_secret_value()
return f"postgresql://{settings.db_user}:{password}@{settings.db_host}:5432/app"
app = FastAPI()
@app.get("/debug/config")
def show_config(settings: Settings = Depends(get_settings)) -> dict:
# Logging the wrapper is safe: db_password=SecretStr('**********')
print(repr(settings))
# Return only non-secret fields rather than relying on masking in the response.
return {"db_host": settings.db_host, "db_user": settings.db_user}
A FastAPI settings class that reads db_password from a mounted file in /run/secrets as a SecretStr. The value stays masked when the settings object is printed, and get_secret_value() is called in one auditable function whose plain-string result is no longer masked.
How do you wire settings into FastAPI dependencies and fail fast at startup?
Wrap settings construction in a zero-argument function decorated with functools.lru_cache, and have route handlers receive the result through Depends(get_settings). The cache matters because Settings() reads the environment, parses any dotenv file and checks every secret file on each call. Without it, that work happens on every request that declares the dependency. With it, the first call builds the object and every later call returns the same instance.
On its own, the first call happens lazily, on the first request that needs settings. A missing DATABASE_URL would then appear as a 500 error minutes after a deploy that looked healthy. To catch it earlier, call get_settings() inside the lifespan handler before the yield. A ValidationError raised there aborts startup, the server process exits, and the orchestrator's readiness check fails before any traffic is routed to the pod. Because the call fills the cache, startup and request handling share one validated instance.
The trade-off is that lru_cache makes a process-wide singleton. If you change an environment variable or rotate a mounted secret file, the running process keeps its old values until it restarts or something calls get_settings.cache_clear(). Plan for rolling restarts, or for secrets that change at runtime, read those values fresh instead of caching them.
Importing a module-level settings = Settings() object is simpler and has no Depends boilerplate. The cost is that validation runs at import time, which also breaks tooling that only wants to import your modules. Every consumer also binds to that one object, so swapping it out or running two configurations in one process means patching module globals. Dependency injection is more verbose, but it shows which handlers depend on configuration and gives you a single point at which to substitute it.
How do you override settings in FastAPI tests?
The cleanest way to change configuration in a FastAPI test is to replace that single dependency. FastAPI's app.dependency_overrides maps a dependency callable to a substitute. Key it on get_settings and point it at a function that returns a Settings instance built with explicit keyword arguments, such as a SQLite database URL or a feature flag turned off. Every handler that declares Depends(get_settings) receives the test instance, and no environment variables are touched. Call app.dependency_overrides.clear() in teardown so the override does not carry over to other tests.
Unit tests that never go through the HTTP layer don't need the app. Construct Settings(...) directly with initializer arguments. By default, init kwargs take precedence over environment variables and dotenv files, so the values you pass are the values you get. Fields you leave out still fall back to the environment, though. Remove stray variables with pytest's monkeypatch.delenv, or pass _env_file=None to skip dotenv loading, when a test must not pick up a developer's local .env.
The lru_cache on get_settings causes subtle failures. Code that calls get_settings() directly, such as a lifespan handler or a module-level client, bypasses dependency_overrides and returns whatever was cached first. An autouse fixture that calls get_settings.cache_clear() before and after each test makes every test start cold, so one test's configuration cannot leak into the next.
This also helps with debugging. When a bug appears only under staging's configuration, you can encode that configuration as constructor arguments in a failing test. Nobody has to export variables in a shell, remember to unset them, or ask "which env was I in?" The reproduction lives in version control and runs the same way in CI.
How can pydantic-settings save engineering time?
Most of the savings come from moving configuration failures earlier and making configuration easier to read. The mechanisms are concrete:
- Misconfiguration fails at deploy, not in production traffic. A missing variable, a malformed DSN, or
debug=truein production raises aValidationErrorat startup that names the field. The alternative is aKeyErrororNonedeep in a code path that may run hours later, followed by log searching to work out which variable was wrong. A failed rollout with a precise error is usually a one-line fix to a manifest. - No hand-written parsing code to maintain. Converting
"20"to an int,"false"to a bool, or a URL string to a validated DSN is done by declared types. Nobody writes, reviews, or debugs one-offint(os.getenv(...))conversions or their edge cases, such asbool("false")beingTrue. - One place to look. The
Settingsclass lists every value the service reads, with its type and default. New engineers, reviewers, and operators writing a deployment manifest read one class instead of searching the codebase forgetenvcalls. Adding a variable is a reviewable diff to that class. - Cheaper tests and reproductions. Constructor arguments and
dependency_overridesreplace environment patching. Environment-specific bugs can be reproduced as committed tests rather than shell sessions. - Fewer secret-leak cleanups.
SecretStrmasking reduces how often a credential ends up in logs or tracebacks, along with the rotation and incident work that follows.
To size the benefit for your own team, an illustrative estimate with assumed inputs: assume a team hits 2 configuration-related incidents per month that are only noticed after deploy, and each takes an assumed 2 hours to diagnose and fix, roughly 4 engineer-hours a month. If boot-time validation turns most of those into failed rollouts that take an assumed 15 minutes to correct, the recurring time drops to about 30 minutes a month. That is set against a one-time cost of writing the Settings class and moving existing getenv calls onto it. These figures are not measurements. Substitute your own incident counts and fix times.
When should you avoid pydantic-settings, and what are the alternatives?
The basic pattern assumes configuration is read once, at startup. That breaks down when secrets rotate. If a database password is reissued by an external secret manager every few hours, a cached settings object will hold the stale value until the process restarts. You then need a refresh strategy, such as re-reading on a schedule, re-resolving the credential when authentication fails, or rolling restarts. Alternatively, you write a custom settings source that fetches from the manager. Neither comes free. The source handles loading, but caching, retries and rotation timing are still your code.
At the other end, a twenty-line maintenance script that reads one token gains little from a model class and an extra dependency.
| Approach | Validation | Typing | Secret handling | Test overrides | Maintenance effort |
|---|---|---|---|---|---|
Plain os.environ reads |
None unless hand-written | Strings only | Values print in full | Patch the environment | Low at first, grows with every new variable |
| Dataclass with manual parsing | Whatever you write | Declared, not enforced | Manual masking | Pass constructor arguments | Moderate; parsing code is yours to keep correct |
BaseSettings |
Declarative, at load time | Enforced and coerced | SecretStr masking |
Constructor arguments or dependency override | Model upkeep plus version pinning |
| Custom settings source | Inherits the model's rules | Enforced | Can fetch from a manager | Same as BaseSettings |
Highest; you own fetch, cache and refresh logic |
The cost of BaseSettings is front-loaded. You spend time modeling fields once, and you pin the library because its source-ordering and parsing behavior can shift between releases. In return, a missing or malformed variable fails at deploy time instead of surfacing later in a rarely used code path. New engineers can also read one class to learn what the service needs, rather than searching the codebase for scattered getenv calls.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to pydantic settings fastapi, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.