Pydantic BaseSettings: Typed, Layered Configuration

Why it exists

Applications need configuration like API keys and database URLs. Managing these as simple strings across different environments (dev, staging, prod) is error-prone and lacks validation. Hardcoding is inflexible, and basic environment variable parsing doesn't offer structure or type safety.

The mental model

Think of BaseSettings as a contract for your application's configuration. You define a Python class with typed attributes (e.g., api_key: str, port: int). Pydantic then acts as a broker, automatically finding, parsing, and validating values for these attributes from a prioritized list of sources.

How it works

You create a class that inherits from pydantic_settings.BaseSettings. For each field in your class, like db_host, Pydantic attempts to find a value. By default, it first checks for an environment variable named DB_HOST (case-insensitively). If not found, it might check a loaded .env file, and finally fall back to a default value if one is defined in the class. If a value is found, it's parsed and validated against the field's type, converting the string "8080" to the integer 8080 automatically. You can also define nested models for structured settings.

When to use it

Use it for any Python application requiring configuration, especially web services built with FastAPI or Flask. It is invaluable when deploying to containerized environments like Docker or Kubernetes, where environment variables are standard. It also simplifies local development by seamlessly integrating with .env files.

When not to use it

For extremely simple scripts with only one or two configuration values, it might be overkill; Python's os.getenv() could suffice. It is not a replacement for dynamic configuration systems like etcd or Consul if you need to change settings in a running application without a restart, as BaseSettings loads configuration at initialization time.

One canonical example

Imagine a Settings class inheriting from BaseSettings with three fields: app_name: str = "Default Name", database_url: str, and max_connections: int = 10. If you create an instance config = Settings(), Pydantic will look for sources. If you have a .env file containing DATABASE_URL="postgres://...", config.database_url will be populated and validated. If you then set an environment variable export MAX_CONNECTIONS=20, config.max_connections will become 20, overriding the default 10 because environment variables have higher priority than defaults.