NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI, #74 most downloaded on PyPI
Settings management using Pydantic
Latest stable
2.16.3
Last release 9 days ago
13 Nov 2026
Ships fairly regularly
a new release about every 2 months
Nearly every release is documented
notes for 38 of 40 stable releases
Nothing withdrawn
no release was ever pulled
7 years old
49 releases · first in 2019
Drag across the ruler to compare, or tap a release to open it.
This patch release fixes a security issue in the default secrets source, a regression from 2.14.2 that dropped nested secrets on Kubernetes, and a Cli
This patch release fixes a security issue in the default secrets source, a regression from 2.14.2 that dropped nested secrets on Kubernetes, and a CliApp.serialize round-trip bug with CliUnknownArgs.
SecretsSettingsSource no longer follows symlinks that resolve outside secrets_dir (#1138, fixes #1137). A secret file that is a symbolic link to a file outside secrets_dir was read into the matching field, so anyone who could place a link in secrets_dir could make the application load any file it can read. This is the plain-source counterpart of GHSA-4xgf-cpjx-pc3j, whose fix in 2.14.2 covered only NestedSecretsSettingsSource. Links that stay inside secrets_dir, such as the Kubernetes secret volume layout (passwd linking to ..data/passwd), still work.secrets_dir is now skipped with a warning instead of being read (#1138). If you deliberately point secret files at targets elsewhere on disk, move or copy the targets into secrets_dir, or point secrets_dir at the directory that holds them.NestedSecretsSettingsSource skips hidden entries (names starting with .) again, as it did before 2.14.2, and stops with a SettingsError after 10,000 entries (#1070).Secrets
secrets_nested_subdir=True, a directory reached through a second symlink is loaded again (#1070, fixes #1061). Since 2.14.2, only the name that sorted first was walked, so the standard Kubernetes secret volume layout (db linking to ..data/db) silently lost its nested secrets.secrets_dir is skipped instead of aborting the load with RuntimeError on Python 3.11 and 3.12 (#1070, #1138).CLI
CliApp.serialize keeps each level's CliUnknownArgs before that level's subcommand token (#1050, fixes #1048). They were emitted after the last subcommand, so parsing the output again moved a parent's unknown args onto the subcommand.Full Changelog: v2.16.2...v2.16.3
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Co-authored-by: Claude Opus 5.5 (1M context) noreply@anthropic.com
Co-authored-by: Claude Opus 5.5 (1M context) noreply@anthropic.com
This patch release fixes env decoding of nested dictionary values, CliApp handling of AliasPath, nested secrets directory precedence and discriminated union defaults with nested_model_default_partial_update.
secrets_dir on NestedSecretsSettingsSource now takes precedence (#1093). Previously it was ignored when the wrapped SecretsSettingsSource inherited a directory from model config, and an explicit empty list was masked too. The order is now: the wrapper's secrets_dir argument, then the wrapped source's directory, then model config. If you pass both Settings(_secrets_dir=...) and NestedSecretsSettingsSource(..., secrets_dir=...), the wrapper's argument now wins.Env and dotenv sources
dict[str, list[str] | str] or dict[str, list[str] | None], now JSON-decode values set through env_nested_delimiter (#1089, #1097). Only JSON arrays and objects are decoded, so plain values like 123, true or "quoted" are kept as strings. Decoding follows enable_decoding and the NoDecode/ForceDecode of the field that holds the dict, and type aliases and Annotated value types are resolved.dict[str, list[dict[str, str]]] are decoded at the right level again (#1109), so APP_VALUES__X='[{"k":"v"}]' no longer reaches validation as a string.CLI
CliApp.run now rebuilds AliasPath inputs for BaseModel and pydantic dataclass commands (#1096). A supplied path used to be reduced to the field name, which failed validation. AliasChoices priority is respected and unsupplied path defaults are left to the model.Discriminated union defaults
nested_model_default_partial_update=True, inner discriminated unions written as Annotated[..., Field(discriminator='...')] are now detected (#1076). When the incoming tag selects another member, the default's fields are no longer merged into it.NameError when another field of the dataclass has a string annotation naming a local class (#1077). Only the discriminator's own annotation is resolved now.Full Changelog: v2.16.1...v2.16.2
This patch release fixes two CLI regressions introduced in 2.16.0.
This patch release fixes two CLI regressions introduced in 2.16.0.
CLI
CliPositionalArg[tuple[int, int]] and NamedTuples are single-valued again (#1069). Since 2.16.0 they were treated as variadic, so a CLI either refused to start with a SettingsError or put the wrong argument into the tuple. Variable-length tuples (tuple[int, ...] and bare Tuple) are still variadic.type ListOfDict = list[dict[str, int]], accepts a JSON list again (#1049). Since 2.16.0, --xx '[{"a":1},{"b":2}]' was merged into the single dict {"a": 1, "b": 2} and failed validation.Full Changelog: v2.16.0...v2.16.1
python-dotenv>=1.2.2 is now required ( #971 ) to pick up the fix for CVE-2026-28684 .
tomli fallback is gone in favor of stdlib tomllib; the toml extra is kept as an empty extra so pip install pydantic-settings[toml] keeps working.python-dotenv>=1.2.2 is now required (#971) to pick up the fix for CVE-2026-28684.validate_by_alias=False (#1033). Env vars, secrets, CLI flags and defaults now use only field names, matching pydantic. An env var named after the alias is now ignored instead of raising extra_forbidden, and the CLI exposes --apple rather than --pomo.validation_alias takes precedence over alias (#1038). When the two differ, values from JSON/YAML/TOML files and the CLI were silently ignored; they now load. CLI help lists the validation_alias flag first, and CliApp.serialize emits it.case_sensitive=False, args after -- and those captured by CliUnknownArgs keep their case (-Xmx4G no longer becomes -xmx4g). Unrecognized options are now reported as typed (--NOPE instead of --nope).json_file_encoding/yaml_file_encoding still override it.nested_model_default_partial_update=True: the default is only dropped when the incoming value selects a different union member.CliApp.run and validate_by_alias=False handling; both are fixed.Settings.settings_cached() and Settings.settings_clear_cache() (#952). These give you a process-local singleton per settings class without hand-rolling lru_cache wrappers. Calling the class directly still builds a fresh instance.AWSSystemsManagerSettingsSource (#941). It recursively reads every parameter under an ssm_path, with / mapping onto nested models. Install it with the new aws-systems-manager extra.env_file_depth (#940) lets a relative env_file be found in parent directories, mirroring pyproject_toml_depth. This is useful when scripts run from a subdirectory of a monorepo. It defaults to 0, which keeps the current behavior.CliVariadicArg for named variadic options (#949, #958). It accepts --param a b c in addition to repeated --param a --param b. Required fields need at least one value.CLI
CliApp.serialize output now round-trips through CliApp.run for enums, tuples, dates and Decimals (#988), explicit None values (#981), empty containers (#1008), CliVariadicArg values (#976) and populated CliUnknownArgs fields, which previously raised IndexError (#992).--items []) now give an empty list instead of [''] (#994).frozenset, MutableSequence and other collection subtypes are now treated as repeatable/variadic options (#972), and so are named collection type aliases such as TypeAliasType('Addrs', list[IPvAnyAddress]) (#1032).cli_exit_on_error=False is now honored in CliSubCommand parsers, which raise SettingsError instead of exiting (#977).CliSubCommand aliases keep their case with case_sensitive=False (#989).CliUnknownArgs field now receives only its own subcommand's leftover args (#1004).CliApp.format_help no longer crashes when cli_prefix is set in model_config (#945).Type aliases and parsing
TypeAliasType('V', list[int] | str)) now decode like their inline equivalents in env and dotenv sources, including under Optional, Annotated and custom validation aliases (#1006, #1030, #1041).Annotated type alias no longer mutates shared FieldInfo metadata, which made validators run twice on subclasses or after model_rebuild() (#979).AliasPath('SOME_KEY') no longer tries to JSON-decode plain string values (#980).collections.abc.Set/MutableSet/typing.AbstractSet fields now JSON-decode env values (#973).typing.Dict field with env_nested_delimiter no longer raises IndexError, which was a regression in 2.13.0 (#1009).Dotenv, secrets and config files
extra='allow', a non-lowercase env_prefix is now stripped from dotenv extras (#959, #968).secrets_case_sensitive=True is now honored on Windows (#1001).~ paths are now expanded when checking that the file exists (#1034), and an explicit toml_table_header=() now overrides the model config to read the file root (#1027).Cloud sources
env_parse_none_str (#1019, #1040).dash_to_underscore=True now works for nested model fields (#1025).NestedSecretsSettingsSource now validates its specific constructor arguments (#975).DotenvFiltering is exported from pydantic_settings.sources.types (#944).strict, extra, context) passed to model_validate() are not applied to BaseSettings, and give a workaround (#1017).extra='forbid' doesn't reject misspelled top-level env vars (#986).populate_by_name (#933), and add a nested model example for env_prefix_target (#953).NestedSecretsSettingsSource specific arguments by @makukha in #975CliApp.serialize output parseable for enum and non-JSON values by @SulimanAbdulrazzaq in #988CliApp.serialize for models with CliUnknownArgs fields by @truecallerabreham in #992secrets_case_sensitive on Windows by overriding _load_env_vars by @hramezani in #1001samuelcolvin/check-python-version action to v5.1 by @Viicos in #1014validate_by_alias=False on pydantic 2.14 by @maharanay22 in #1022validate_by_alias=False by @hramezani in #1033Note truncated.
case_sensitive now applies to init kwargs and config-file sources ( #900 ). InitSettingsSource and the JSON/TOML/YAML config sources previously ignore
case_sensitive now applies to init kwargs and config-file sources (#900). InitSettingsSource and the JSON/TOML/YAML config sources previously ignored case_sensitive. Since it defaults to False, case-insensitive matching is now the default for these sources — e.g. Settings(TeSt=...) now populates a test field where it previously did not. Nested keys are still matched case-sensitively.IncompleteFieldDefinitionWarning telling you to call model_rebuild(). If you have filterwarnings = error configured, this may surface as a new failure.ValidationError (#926) instead of a less specific error.cli_show_env_vars=True (#860), so generated --help output doubles as configuration documentation.PYDANTIC_SETTINGS_DEBUG for debugging settings resolution (#906, #913). Set it to a truthy value with DEBUG logging enabled to see each source's contribution in priority order, which source won for each value, and which env_file/secret files were probed, loaded, or skipped — the long-standing "why isn't my .env being picked up?" question.toml_table_header for regular TOML files (#882, #886, #887), letting you root settings at a nested table in any TOML file, not just pyproject.toml.Traversable support for JSON/TOML/YAML file sources (#902), so you can load config packaged inside a distribution — including files inside a zip or wheel — via importlib.resources.files(...) without casting to Path.project_id can come from an earlier settings source (#878), rather than only from the constructor or GOOGLE_CLOUD_PROJECT.case_sensitive=True (#894). Windows upper-cases os.environ keys, so fields raised Field required instead of picking up their values.AliasPath on nested model fields not JSON-decoding env values (#898).dbx_token being swallowed by a db: dict field.nested_model_default_partial_update=True corrupting discriminated unions (#876).Secret subclasses crashing when loaded from the environment (#920).Optional[Annotated[MyEnum, ...]] with env_parse_enums=True (#910).yaml_config_section now falls back to defaults instead of raising AttributeError: 'NoneType' object has no attribute 'keys' (#914).NestedSecretsSettingsSource no longer follows symlinks pointing outside secrets_dir (#889).list_secrets call when case_sensitive=True (#862), lowering the required IAM permissions to just roles/secretmanager.secretAccessor.types-boto3[secretsmanager] is no longer required at runtime (#880).Full Changelog: v2.14.1...v2.15.0
This is a security patch release.
This is a security patch release.
NestedSecretsSettingsSource from following symlinks outside secrets_dir by @hramezani in #889Fixes GHSA-4xgf-cpjx-pc3j: NestedSecretsSettingsSource with secrets_nested_subdir=True could follow a symbolic link inside secrets_dir pointing outside it, reading out-of-tree files into settings values and bypassing the secrets_dir_max_size cap. Affected versions: >= 2.12.0, < 2.14.2.
Full Changelog: v2.14.1...v2.14.2
Bump the python-packages group with 4 updates by @dependabot [bot] in #850
cls conflicting with classmethod parameter by @hramezani in #858Full Changelog: v2.14.0...v2.14.1
Fix parsing env vars into Optional Strict types by @hramezani in #792
Literal[numeric Enum] coercion for CLI and env vars by @m9810223 in #811boto3-stubs to types-boto3 by @hramezani in #831BaseSettings.__init__() by @Viicos in #842cli_ignore_unknown_args=True not working on subcommands by @hramezani in #844python -OO by falling back to json_schema_extra by @hramezani in #843Full Changelog: v2.13.1...v2.14.0
Fix regression for bool fields since 2.13.0 by @hramezani in #784
Full Changelog: v2.13.0...v2.13.1
fix: Deterministic alias selection when using validate_by_name by @chbndrhnns in #707
None for inaccessible GCP Secret Manager secrets by @zaphod72 in #712NoDecode by @tselepakis in #695NAME environment variable in WSL by @kzrnm in #747(default: …) in the help message for CliToggleFlag by @kzrnm in #740snake_case_conversion with env_prefix for Azure Key Vault source by @cstarkers in #762Full Changelog: v2.12.0...v2.13.0
Support for enum kebab case. by @kschwab in https://github.com/pydantic/pydantic-settings/pull/686
Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.11.0...v2.12.0
CLI Serialize Support by @kschwab in https://github.com/pydantic/pydantic-settings/pull/643
CliSettingsSource.__init__. by @trygve-baerland in https://github.com/pydantic/pydantic-settings/pull/656InitSettingsSource resolution deterministic by @enrico-stauss in https://github.com/pydantic/pydantic-settings/pull/681Full Changelog: https://github.com/pydantic/pydantic-settings/compare/2.10.1...v2.11.0
Fix UnboundLocalError error in _replace_field_names_case_insensitively by @hramezani in #639
Full Changelog: 2.10.0...2.10.1
Full Changelog: https://github.com/pydantic/pydantic-settings/compare/2.10.0...2.10.1
Fix running tests when azure-keyvault-secrets is not installed by @CyberTailor in #601
cli_shortcuts to CLI settings by @karta9821 in #624Full Changelog: v2.9.1...2.10.0
cli_shortcuts to CLI settings by @karta9821 in https://github.com/pydantic/pydantic-settings/pull/624Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.9.1...2.10.0
fix: Expose ConfigFileSourceMixing on top level sources/__init__.py by @jbw-vtl in https://github.com/pydantic/pydantic-settings/pull/597
Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.9.0...v2.9.1
Drop support for Python 3.8 by @Viicos in https://github.com/pydantic/pydantic-settings/pull/560
typing-inspection by @Viicos in https://github.com/pydantic/pydantic-settings/pull/556uv for Project Management by @KanchiShimono in https://github.com/pydantic/pydantic-settings/pull/547Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.8.1...v2.9.0
Fix for init source kwarg alias resolution. by @kschwab in https://github.com/pydantic/pydantic-settings/pull/550
BaseSettings.__init__ by @Viicos in https://github.com/pydantic/pydantic-settings/pull/557object instead of Any by @Viicos in https://github.com/pydantic/pydantic-settings/pull/559Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.8.0...v2.8.1
CLI support for optional and variadic positional args by @kschwab in https://github.com/pydantic/pydantic-settings/pull/519
Any in BaseSettings signature to avoid mypy errors by @Viicos in https://github.com/pydantic/pydantic-settings/pull/529Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.7.1...v2.8.0
Move preferred alias resolution to private method by @kschwab in https://github.com/pydantic/pydantic-settings/pull/507
Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.7.0...v2.7.1
Fix test_protected_namespace_defaults with -Wdefault by @CyberTailor in https://github.com/pydantic/pydantic-settings/pull/462
test_protected_namespace_defaults with -Wdefault by @CyberTailor in https://github.com/pydantic/pydantic-settings/pull/462__repr__ implementations by @dlax in https://github.com/pydantic/pydantic-settings/pull/465NoDecode and ForceDecode annotations by @hramezani in https://github.com/pydantic/pydantic-settings/pull/492Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.6.1...v2.7.0
Add Python 3.13 support by @hramezani in https://github.com/pydantic/pydantic-settings/pull/450
Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.6.0...v2.6.1
Fix nested model field with alias parsing by @hramezani in https://github.com/pydantic/pydantic-settings/pull/400
cli_ignore_unknown_args config option. by @kschwab in https://github.com/pydantic/pydantic-settings/pull/405cli_flag_prefix_char config option. by @kschwab in https://github.com/pydantic/pydantic-settings/pull/418Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.5.2...v2.6.0
Second fix for the TypeError bug introduced in 2.5 by @hramezani in https://github.com/pydantic/pydantic-settings/pull/396
Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.5.1...v2.5.2
Fix TypeError introduced in 2.5 by @hramezani in https://github.com/pydantic/pydantic-settings/pull/392
Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.5.0...v2.5.1
Fix a bug in nested vanila dataclass by @hramezani in https://github.com/pydantic/pydantic-settings/pull/357
nested_model_default_partial_update flag and DefaultSettingsSource by @kschwab in https://github.com/pydantic/pydantic-settings/pull/348Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.4.0...v2.5.0
Deprecate read_env_file and move it to DotEnvSettingsSource by @WarpedPixel in https://github.com/pydantic/pydantic-settings/pull/318
read_env_file and move it to DotEnvSettingsSource by @WarpedPixel in https://github.com/pydantic/pydantic-settings/pull/318Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.3.4...v2.4.0
add in-place reloading in docs by @nrolin in https://github.com/pydantic/pydantic-settings/pull/316
pydantic docs build by @sydney-runkle in https://github.com/pydantic/pydantic-settings/pull/321Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.3.3...v2.3.4
Fix an intriduced bug in parsing json field with discriminated union by @hramezani in https://github.com/pydantic/pydantic-settings/pull/312
Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.3.2...v2.3.3
Initialize CLI source on demand. by @kschwab in https://github.com/pydantic/pydantic-settings/pull/305
argparse formatting problem by @scottstanie in https://github.com/pydantic/pydantic-settings/pull/307Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.3.1...v2.3.2
Fix a regression in parsing env value for nested dict by @hramezani in https://github.com/pydantic/pydantic-settings/pull/301
Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.3.0...v2.3.1
Add environment parsing support for enums. by @kschwab in https://github.com/pydantic/pydantic-settings/pull/252
explode_env_vars for better dict handling by @hramezani in https://github.com/pydantic/pydantic-settings/pull/261PyprojectTomlConfigSettingsSource by @ITProKyle in https://github.com/pydantic/pydantic-settings/pull/255Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.2.1...v2.3.0
respect env_prefix when extra allowed by @zzstoatzz in https://github.com/pydantic/pydantic-settings/pull/238
env_prefix when extra allowed by @zzstoatzz in https://github.com/pydantic/pydantic-settings/pull/238Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.2.0...v2.2.1
Fix documentation and update pydantic and pydantic-core dependancies by @Xunop in https://github.com/pydantic/pydantic-settings/pull/194
Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.1.0...v2.2.0
Fix code for mentioned variable in Settings Management by @ikosmala in https://github.com/pydantic/pydantic-settings/pull/146
Environment variable names section by @iagorrr in https://github.com/pydantic/pydantic-settings/pull/173Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.0.3...v2.1.0
Fix _replace_field_names_case_insensitively precondition inconsistency by @AlexVndnblcke in https://github.com/pydantic/pydantic-settings/pull/130
_replace_field_names_case_insensitively precondition inconsistency by @AlexVndnblcke in https://github.com/pydantic/pydantic-settings/pull/130Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.0.2...v2.0.3
dotenv no error w/ an env key shorter than prefix (#106) by @jvllmr in https://github.com/pydantic/pydantic-settings/pull/107
pydantic_settings.SettingsConfigDict instead of pydantic.ConfigDict in tests by @hramezani in https://github.com/pydantic/pydantic-settings/pull/119fiel_value -> field_value) by @kkirsche in https://github.com/pydantic/pydantic-settings/pull/123Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.0.1...v2.0.2
pydantic V2 is released by @davidhewitt in https://github.com/pydantic/pydantic-settings/pull/99
BaseSettings.model_config by @Viicos in https://github.com/pydantic/pydantic-settings/pull/97DotenvType to accept str by @hramezani in https://github.com/pydantic/pydantic-settings/pull/96PydanticBaseEnvSettingsSource.__init__ by @hramezani in https://github.com/pydantic/pydantic-settings/pull/100Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.0.0...v2.0.1
Add mkdocs.yml to run mkdocs locally by @Kludex in https://github.com/pydantic/pydantic-settings/pull/67
mkdocs.yml to run mkdocs locally by @Kludex in https://github.com/pydantic/pydantic-settings/pull/67mkdocs.yml by @Kludex in https://github.com/pydantic/pydantic-settings/pull/70SettingsConfigDict public by @Kludex in https://github.com/pydantic/pydantic-settings/pull/75index.md by @Kludex in https://github.com/pydantic/pydantic-settings/pull/73case_sensitive and env_prefix usable as args by @Viicos in https://github.com/pydantic/pydantic-settings/pull/76assignees list to the hooky config by @hramezani in https://github.com/pydantic/pydantic-settings/pull/92Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.0b1...v2.0.0
Nothing published for this version
Format docs for import by @tpdorsey in https://github.com/pydantic/pydantic-settings/pull/48
Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.0a4...v2.0b1
Add Pydantic PyPI classifier by @Kludex in https://github.com/pydantic/pydantic-settings/pull/36
Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.0a3...v2.0a4
Implement proper support for nested complex env values by @hramezani in https://github.com/pydantic/pydantic-settings/pull/22
Full Changelog: https://github.com/pydantic/pydantic-settings/compare/v2.0a1...v2.0a3
Reimplement setting source classes by @hramezani in https://github.com/pydantic/pydantic-settings/pull/15
Full Changelog: https://github.com/pydantic/pydantic-settings/commits/v2.0a1
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per quarter.