pydantic-settings: configuration as a validated model, with secrets backends and dotenv

What the package does, and where it sits

pydantic-settings is settings management using Pydantic, and it is a small package with a large job. It reads configuration from the environment and from files, validates it through a Pydantic model, and gives you an object with typed attributes instead of a bag of strings.

The problem it solves is the one every service hits eventually. A dozen os.environ lookups in a dozen modules is not configuration, it is a distributed stringly typed mess, and the failure mode is a KeyError in production or, worse, a string where an int was expected. A settings model turns that into a startup error with a clear message.

The package sits inside the wider Pydantic ecosystem. The README describes the Pydantic Stack as everything you need to ship production-grade AI agents, and lists Pydantic AI as a type-safe agent framework, Pydantic Logfire as AI-first full-stack observability, and the Logfire AI Gateway as a unified LLM proxy. The settings package is the part of that stack that decides what your application is configured to do before it does anything.

The project is MIT licensed, and it is maintained by Samuel Colvin, Eric Jolibois and Hasan Ramezani, which is the Pydantic core team rather than a separate group. The repository is not archived, the last push was on 2026-10-16, and the recent releases are v2.16.0 from 2026-10-14, v2.15.0 from 2026-08-07 and v2.14.2 from 2026-06-19. The package metadata marks it as Production/Stable, and the CI and coverage badges are both wired to codecov and GitHub Actions.

The layout is conventional: the pydantic_settings package directory, a tests directory, a docs directory with an mkdocs.yml, a Makefile, a uv.lock and a pre-commit configuration.

The dependency set, and what the extras add

The runtime dependencies are four, and they are the minimum a settings loader can get away with.

pydantic at 2.7.0 or newer is the model engine. python-dotenv at 1.2.2 or newer is what lets a .env file be read as a source of configuration. typing-extensions at 4.0.0 and typing-inspection at 0.4.0 are there for the typing features the library exposes on Python versions where the standard library typing module is behind.

The optional dependencies are where the interesting decisions are.

The yaml extra adds pyyaml at 6.0.1 or newer, so you can read configuration from a YAML file rather than only from the environment. The toml extra is explicitly empty, with a comment explaining that it is kept for backwards compatibility because tomllib is part of the standard library since Python 3.11. That is a nice detail: the extra still exists so that existing install commands do not break, but it installs nothing.

Then there are the secret backends, and they are the reason to use this package rather than a hand-rolled env reader. The azure-key-vault extra brings azure-keyvault-secrets at 4.8.0 or newer and azure-identity at 1.16.0 or newer. The aws-secrets extra is listed, and the list continues past the point the excerpt shows.

That list of extras is the feature that distinguishes pydantic-settings from a dotenv parser. A service that runs on Azure App Service or in AWS ECS often has its secrets in the platform's secret store rather than in the environment, and the point of an extra per backend is that the same Pydantic model works whether the value came from a variable, a file, or a secret manager, with the validation unchanged.

The Python floor is worth noting: requires-python is 3.11 or newer, and the classifiers list 3.11 through 3.15.

The build targets, and the constraint file CI installs

The Makefile shows a project that takes its build reproducibility seriously, and one target in particular explains why.

The install target runs uv sync with all extras and all groups, so a contributor's environment matches the full dependency matrix rather than a subset. The refresh-lockfiles target runs uv lock -U.

Then there is build-constraints, and it is the interesting one:

uv run --no-project python -c "import tomllib; print('\n'.join(tomllib.load(open('pyproject.toml', 'rb'))['build-system']['requires']))" \
		| uv pip compile - --universal --python-version 3.11 --generate-hashes --upgrade \
			--custom-compile-command 'make build-constraints' -o .github/build-constraints.txt

It reads the build-system requires list out of pyproject.toml, compiles it into a hashed constraints file at .github/build-constraints.txt, and pins the Python version to 3.11 for the universal resolution. The point is that the build backend and its dependencies are locked with hashes, so a compromised or drifted build dependency cannot enter the build of a released artifact. For a package whose whole job is to hold secrets, that is a proportionate amount of care, and it is unusual to see.

The rest of the Makefile is the usual. format runs ruff check --fix and ruff format over the pydantic_settings and tests sources, lint runs the same without fix, mypy runs against pydantic_settings only, and test runs coverage run -m pytest with the ten slowest durations printed. The all target chains lint, mypy and testcov.

The build backend is hatchling, and the version is read from a path in the project metadata, pydantic_settings/version.py, which is the standard way to have one file hold the version for both the package and the changelog tooling.

Where the documentation lives and what it has to answer

The README is short, and that is because the detail lives in the documentation site rather than in the repository. The link is pydantic.dev/docs/validation/latest/concepts/pydantic_settings/, and the repository itself has a docs directory with an mkdocs.yml, so there is a documentation build in the tree as well.

The questions that documentation has to answer are the ones that decide whether the package works for you, and they are worth listing before you commit.

Where does each value come from. Environment variables are the obvious source, and a .env file is a second one, but a project that installs the azure-key-vault or aws-secrets extra has a third. When a field is present in more than one source, the order decides the outcome, and that order is a property of the configuration rather than of your deployment, which is exactly why it needs to be written down rather than discovered.

How nested keys map to environment variable names. A settings model with a nested structure has to flatten into names like DATABASE__HOST or similar, and the convention has to be fixed across your team, since two services with different conventions will behave differently under the same deployment configuration.

What happens when a required value is missing. The whole point of validating at startup is that a missing value fails immediately and loudly, and the exact exception and message are what a developer sees at 3am.

And how a value is parsed. A field typed as an integer receives a string from the environment, so the conversion rules, including what happens for a value that looks numeric but is not, are part of the contract.

The repository also carries a CHANGELOG, a CODE_OF_CONDUCT.md, a CONTRIBUTING.md and a pre-commit configuration, plus a .yamlfmt.yaml, which suggests the project formats its own YAML configuration files as part of the pre-commit run.

What the settings model does not do for you

The first limitation is that settings are read once. The model is instantiated when you construct it, and the values are read at that moment. If you need configuration that changes while the process is running, whether that is a feature flag flipped in a dashboard, a rate limit raised by an operator, or a database URL that is rotated, you need a different mechanism, and no amount of Pydantic validation changes that. The package is a startup-time concern, not a runtime one.

The second limitation is precedence, and it is a documentation question rather than a design one. Configuration can come from several places, and when the same field is present in more than one, something has to win. The README points to the documentation at pydantic.dev for the details, and the ordering of environment variables, dotenv files and secret backends is exactly the kind of thing that surprises people in a deployment where the environment has a value the .env file also has.

The third limitation is scope. This package handles settings, not secrets. It can fetch a secret from a backend, and the azure-key-vault extra exists for that, but what it does not do is decide which values are secrets, rotate them, or audit who read them. The SETTINGS_ENCRYPTION_KEY-style concern, if you have one, is a different layer.

The fourth is the dependency on the wider Pydantic version line. The package requires pydantic at 2.7.0 or newer, so adopting it means adopting or already having a recent Pydantic 2. If your project is on Pydantic 1, this is not a drop-in step, it is a migration of the model layer as well.

On maintenance, the repository is not archived with the last push on 2026-10-16 and a release two days earlier, so the package is being worked on continuously, and it is MIT licensed with the licence in the LICENSE file at the root.

Editorial conclusion

pydantic-settings fits a Python service that has outgrown os.environ and wants configuration validated at startup with typed fields, and it fits a team that already uses Pydantic and wants one model style for config and payloads. It is a poor fit if you need settings that change at runtime without a restart, since the model is built once when you instantiate it, and a poor fit if you are on Python 3.10 or older, since the package requires 3.11 or newer. Before adopting, decide which secret backend you will use and install the matching extra, and check the precedence rules in the documentation, because the order in which environment variables, dotenv files and secret backends are read decides which value wins when more than one is present.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. pydantic/pydantic-settings on GitHub
4. README
5. Releases