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?
answer
- separate package since version 2
- field name is the variable name
- case-insensitive by default
- strings validated like any input
- missing error at construction
basics
~20 sInstantiating 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 sIn 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 linesimport 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 ordersgo deeper
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.
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.
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.
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.