skip to content

Settings Management

BaseSettings reads environment variables, .env files and secrets into one typed, validated object with a defined source priority. Asked about nested names, precedence and keeping secrets out of logs.

on this pageshow

explore

questions

6

In Pydantic 2, how does a pydantic-settings BaseSettings class fill its fields from environment variables, and what happens when a required one is missing?

level: juniorimportance: must knowfreq 72%

answer

  1. separate package since version 2
  2. field name is the variable name
  3. case-insensitive by default
  4. strings validated like any input
  5. missing error at construction

basics

~20 s

Instantiating a BaseSettings subclass reads every field not passed as a keyword argument from an environment variable named after the field, matched case-insensitively, and validates it by type; a missing required field raises ValidationError on the spot.

solid answer

~40 s

In Pydantic 2, `BaseSettings` lives in the separate `pydantic-settings` package (`from pydantic_settings import BaseSettings`); version 1 shipped it inside `pydantic`. Calling `Settings()` gathers a value for each field: a keyword argument wins, otherwise the environment variable named after the field (matched case-insensitively by default), then any configured `.env` file or secrets directory, then the field default. Environment values are strings, so they go through normal validation: `PORT=8080` becomes `8080` for an `int` field, while `list`, `dict` and sub-model fields expect JSON text. A required field with no value anywhere raises `ValidationError` with error type `missing` during construction, and `BaseSettings` validates defaults too (`validate_default=True`), so bad configuration fails at startup instead of on first use.

code

python · 22 lines
python
import os
from pydantic import ValidationError
from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    service_name: str = "orders"
    port: int = 8000
    database_url: str


os.environ["PORT"] = "8080"
try:
    Settings()
except ValidationError as exc:
    print(exc.errors()[0]["type"], exc.errors()[0]["loc"])
    # missing ('database_url',)

os.environ["DATABASE_URL"] = "postgresql://localhost/orders"
settings = Settings()
print(settings.port, settings.service_name)
# 8080 orders

go deeper

for a junior

Recall the import from pydantic_settings, that a field reads the variable with its own name in any case, and that a missing required value raises ValidationError when the object is built.

for a middle

Explain that values arrive as strings and go through normal validation, that complex fields expect JSON, and that BaseSettings validates defaults and forbids extras, unlike BaseModel.

for a senior

Show why eager validation at construction is a deployment safety net: build settings at process start so a bad variable crashes the rollout instead of failing on a rarely used code path.

for a principal

Weigh how much configuration a service should require versus default: every required field is a startup check, and every default is a value nobody will notice is wrong.

## What BaseSettings is `BaseSettings` is a subclass of Pydantic's `BaseModel` built for **application configuration**. You declare fields with type hints exactly as on any model, and when you create an instance, the library fills each field you did not pass as a keyword argument from the outside world: environment variables first, then (if you configure them) a `.env` file and a directory of secret files, and finally the field's default. In **Pydantic 2** the class is no longer part of the `pydantic` package. It moved to the separate `pydantic-settings` distribution: - install it with `pip install pydantic-settings`; - import it with `from pydantic_settings import BaseSettings, SettingsConfigDict`; - `from pydantic import BaseSettings` raises `PydanticImportError` with a message pointing at the new package. Configuration goes in `model_config = SettingsConfigDict(...)`, the settings-specific version of `ConfigDict`. ## How a field finds its variable With no options set, the **variable name is the field name**: 1. A field `database_url` is read from `database_url`, `DATABASE_URL` or any other casing, because `case_sensitive` defaults to `False`. 2. `env_prefix` (default `''`) is glued to the front of every name, so `env_prefix="APP_"` makes it `APP_DATABASE_URL`. 3. `Field(validation_alias="DB_URL")` replaces the name for one field. 4. A keyword argument, `Settings(database_url="...")`, beats every environment source, which is how tests override a value. The class name plays no part in the lookup: a class called `Settings` does not add a `SETTINGS_` prefix. ## From string to typed value Every environment variable is a string, so the library hands it to Pydantic's normal validation, the same path a string passed to the initialiser would take: - simple types (`int`, `float`, `bool`, `str`) are converted by Pydantic's usual rules, so `"8080"` becomes `8080` and `"true"` becomes `True`; - **complex types** (`list`, `set`, `dict`, sub-models) are decoded as **JSON** first, so `ALLOWED_HOSTS='["a.internal", "b.internal"]'` works and `ALLOWED_HOSTS=a.internal,b.internal` raises `SettingsError` because it is not valid JSON; - an empty variable is passed through verbatim, so `PORT=` fails an `int` field unless `env_ignore_empty=True` tells the library to fall back to the default instead. ## What a missing or bad value does Settings are validated **eagerly, when the object is constructed**. Nothing is lazy: | Situation | Result of `Settings()` | |---|---| | required field, no value in any source | `ValidationError`, type `missing` | | `PORT=abc` for `port: int` | `ValidationError`, type `int_parsing` | | non-JSON text for a `list` field | `SettingsError` naming the field and source | | invalid default value | `ValidationError`, because defaults are validated | That last row is a real difference from `BaseModel`. A plain model has `validate_default=False`; `BaseSettings` sets `validate_default=True`, so `port: int = "eighty"` breaks at startup instead of hiding until someone reads it. Two other defaults differ as well: `BaseSettings` sets `extra="forbid"` where `BaseModel` uses `"ignore"`, and it allows arbitrary types. The practical upshot is **fail fast**: build the settings object once while the process starts, and a misconfigured deployment crashes immediately with an error that names the field, instead of serving traffic with a half-valid configuration. ## A worked example ```python import os from pydantic import ValidationError from pydantic_settings import BaseSettings class Settings(BaseSettings): service_name: str = "orders" port: int = 8000 database_url: str os.environ["PORT"] = "8080" try: Settings() except ValidationError as exc: print(exc.errors()[0]["type"], exc.errors()[0]["loc"]) # missing ('database_url',) ``` Once `DATABASE_URL` is set, `Settings().port` is the integer `8080` and `service_name` keeps its default. ## Mistakes interviewers listen for - **Importing from the wrong package.** Version 1 tutorials still show `from pydantic import BaseSettings`; in version 2 that import fails, and `pydantic.v1.BaseSettings` gives you the old class with the old behaviour. - **Assuming upper-case names are required.** Field `port` matches `PORT`, `port` and `Port` unless `case_sensitive=True` is set. - **Expecting comma-separated lists.** `list[str]` wants JSON from the environment; splitting `a,b,c` needs a custom validator together with the `NoDecode` annotation. - **Expecting lazy failure.** Nothing waits until first access; the whole object is valid or the constructor raises. - **Forgetting that defaults are checked.** A wrong-typed default on a settings field is a startup error, not a silent quirk. ## Where the details live Choosing between keyword arguments, `.env` files and secret files, nesting with `env_nested_delimiter`, hiding secrets with `SecretStr` and loading settings once per process each deserve their own discussion. The core idea is the one above: a typed model whose missing inputs are looked up in the environment and validated before your code ever runs.

  • How do you override one setting in a unit test without editing os.environ?
    Pass it as a keyword argument: `Settings(database_url="sqlite://")`. Initialiser arguments outrank every environment source by default. To stop a developer's local `.env` file leaking into the test, also pass `_env_file=None`, which skips dotenv loading for that instance even when `model_config` names a file.
  • What happens to an int field when its environment variable is set but empty?
    The empty string is passed through verbatim and fails integer validation with `int_parsing`. Setting `env_ignore_empty=True` in `SettingsConfigDict` makes the library drop empty variables, so the field falls back to its default, or reports `missing` if it has none.

  • BaseSettings is still imported from the pydantic package in version 2.
  • Environment variables must be upper-case to match a lower-case field name.
  • A missing setting stays None until the code first reads it.
  • Defaults on a BaseSettings field are trusted and never validated.
  • A list field accepts a comma-separated variable such as 1,2,3 by default.

Assumes Pydantic 2 with pydantic-settings 2.15; version 1 shipped BaseSettings inside the pydantic package, and version 2 moved it to pydantic-settings.

open as a page

In pydantic-settings, how do env_prefix and env_nested_delimiter decide which environment variable fills a nested database host field?

level: middleimportance: must knowfreq 62%

basics

~10 s

env_prefix is prepended to every variable name and env_nested_delimiter splits a name into nested keys, so with APP_ and __ the variable APP_DATABASE__HOST fills settings.database.host.

open as a page

In pydantic-settings, what does each Settings() call cost, and how should a service load its settings once per process?

level: middleimportance: should knowfreq 50%

basics

~10 s

Each Settings() call re-reads the environment, the .env file and secret files and revalidates every field, so a service builds one instance at startup, often behind functools.lru_cache, and reuses it.

open as a page

In Pydantic 2, what does typing a settings field as SecretStr keep out of logs, and where can the secret still leak?

level: middleimportance: should knowfreq 58%

basics

~10 s

SecretStr masks the value as ********** in repr, str and JSON dumps, so printing settings is safe; the secret still leaks through get_secret_value() output you log, ValidationError input values, and the settings debug log.

open as a page

In pydantic-settings, why does an unknown line in the .env file stop startup with extra_forbidden, while an unknown environment variable is ignored?

level: seniorimportance: should knowfreq 38%

basics

~20 s

The environment source looks up only declared fields' names, but the dotenv source passes .env entries no field uses into the model as input, and BaseSettings defaults to extra='forbid', so an undeclared entry fails validation.

open as a page

In pydantic-settings, a database password moved to a file in secrets_dir, yet production still connects with an old value - what in the source priority explains it?

level: seniorimportance: should knowfreq 52%

basics

~10 s

By default pydantic-settings ranks initialiser arguments, then environment variables, then the .env file, then secrets_dir files, then defaults; a leftover password variable or .env entry therefore shadows the new secret file.

open as a page