pypi / pydantic-settings

pydantic-settings

What changed in pydantic-settings 2, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-19.

11 breaking3 security9 new APIs and options2 behavior and defaults36 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@unstale/cli 0.2.0 on npm

pydantic-settings 261 changes

Breaking changes 11

With case_sensitive=False, only registered CLI options are lowercased; arguments after -- and CliUnknownArgs values keep their case.
2.16.0release notes
Each CliUnknownArgs field now receives only leftover arguments from its own subcommand.
2.16.0release notes
An empty JSON array now parses as an empty list instead of [''].
2.16.0release notes
JSON config files are read as UTF-8 by default instead of the locale encoding; this option still overrides it.
2.16.0release notes
With this enabled, a discriminated union default is dropped only when the incoming value selects a different union member.
2.16.0release notes
Python 3.10 is no longer supported; pydantic-settings now requires Python 3.11+.
2.16.0release notes
When false, aliases are ignored in every source; environment variables, secrets, CLI flags and defaults use only field names.
2.16.0release notes
Takes precedence over alias when the two differ, so JSON/YAML/TOML file and CLI values load instead of being silently ignored.
2.16.0release notes
YAML config files are read as UTF-8 by default instead of the locale encoding; this option still overrides it.
2.16.0release notes
The setting now applies to init kwargs and JSON/TOML/YAML config-file sources; because it defaults to False, matching is case-insensitive for these sources. Nested keys remain case-sensitive.
2.15.0release notes
Non-JSON environment values for strict fields now raise ValidationError instead of a less specific error.
2.15.0release notes

Security 3

With case_sensitive=True, the GCP source skips the list_secrets call, lowering the required IAM permissions to roles/secretmanager.secretAccessor.
2.15.0release notes
The source no longer follows symlinks that point outside secrets_dir.
2.14.2release notes release notes
pydantic-settings: NestedSecretsSettingsSource follows symlinks outside secrets_dir, enabling local file read and bypassing secrets_dir_max_size
2.14.2security advisory

New APIs and options 9

Adds an extra for installing the AWS Systems Manager Parameter Store source.
2.16.0release notes
Adds an AWS Systems Manager Parameter Store source that recursively reads parameters under an ssm_path, mapping / onto nested models.
2.16.0release notes
Adds named variadic CLI options that accept multiple values after one option as well as repeated options; required fields need at least one value.
2.16.0release notes
Returns a process-local singleton per settings class; calling the class directly still builds a fresh instance.
2.16.0release notes
Clears the cache used for process-local cached settings instances.
2.16.0release notes
Enables environment variable names to appear in generated CLI help, making --help output useful as configuration documentation.
2.15.0release notes
Set this environment variable to a truthy value with DEBUG logging enabled to inspect source contributions, value precedence, and env-file or secret-file resolution.
2.15.0release notes
Lets you root settings at a nested table in any TOML file, rather than only in pyproject.toml.
2.15.0release notes
JSON, TOML, and YAML file sources accept Traversable resources, allowing packaged configuration files, including files in zip or wheel distributions, to be loaded without casting to Path.
2.15.0release notes

Behavior and default changes 2

Fields with unresolved forward references now emit this warning, which tells you to call model_rebuild(); warning-as-error configurations may turn it into a failure.
2.15.0release notes
The GCP settings source can obtain project_id from an earlier settings source, rather than only from the constructor or GOOGLE_CLOUD_PROJECT.
2.15.0release notes

Fixes and other changes 36

A bare single-segment AliasPath no longer tries to JSON-decode plain string values.
2.16.0release notes
Resolving a named Annotated type alias no longer mutates shared FieldInfo metadata, avoiding validators running twice on subclasses or after model_rebuild().
2.16.0release notes
Case-insensitive matching now works for nested pydantic dataclasses.
2.16.0release notes
Tuples, frozenset, MutableSequence and other collection subtypes, including named collection type aliases, are treated as repeatable or variadic options.
2.16.0release notes
cli_exit_on_error=False is now honored by CliSubCommand parsers, which raise SettingsError instead of exiting.
2.16.0release notes
No longer crashes when cli_prefix is set in model_config.
2.16.0release notes
Serialized output now round-trips through CliApp.run for enums, tuples, dates, Decimal values, explicit None, empty containers, CliVariadicArg values, and populated CliUnknownArgs fields.
2.16.0release notes
Serialization now preserves explicit None values.
2.16.0release notes
Serialization now preserves empty containers.
2.16.0release notes
Serialization now handles populated CliUnknownArgs fields without raising IndexError.
2.16.0release notes
Serialized CLI output now parses for enums, tuples, dates and Decimal values.
2.16.0release notes
Serialization now preserves CliVariadicArg values.
2.16.0release notes
Aliases keep their case when case_sensitive=False.
2.16.0release notes
Set, MutableSet and AbstractSet fields now JSON-decode environment values.
2.16.0release notes
dash_to_underscore=True now works for nested Azure Key Vault model fields.
2.16.0release notes
DotenvFiltering is now exported from pydantic_settings.sources.types.
2.16.0release notes
A bare typing.Dict field no longer raises IndexError when env_nested_delimiter is set.
2.16.0release notes
Azure Key Vault and GCP Secret Manager now honor env_parse_none_str.
2.16.0release notes
With extra='allow', a non-lowercase env_prefix is now stripped from dotenv extras.
2.16.0release notes
An empty JSON config file is treated as an empty mapping instead of crashing.
2.16.0release notes
Named union type aliases now decode like inline equivalents in environment and dotenv sources, including under Optional, Annotated and custom validation aliases.
2.16.0release notes
The source now validates its specific constructor arguments.
2.16.0release notes
Adds support for pydantic 2.14, including fixes for CliApp.run and validate_by_alias=False handling.
2.16.0release notes
Adds support for Python 3.15.
2.16.0release notes
secrets_case_sensitive=True is now honored on Windows.
2.16.0release notes
An explicit empty tuple overrides the model config to read the TOML file root.
2.16.0release notes
Home-directory paths are expanded when checking whether the TOML table-header file exists.
2.16.0release notes
Environment values for nested model fields using AliasPath are now JSON-decoded.
2.15.0release notes
Environment variables now load on Windows when case_sensitive=True, despite os.environ keys being upper-cased.
2.15.0release notes
Dotenv extras are no longer wrongly claimed by a complex field that shares their name prefix.
2.15.0release notes
Enum names now parse through nested annotations such as Optional[Annotated[MyEnum, ...]] when enum parsing is enabled.
2.15.0release notes
Case-insensitive field matching now works for optional nested models.
2.15.0release notes
Secret subclasses no longer crash when loaded from the environment.
2.15.0release notes
Secret files are now read as UTF-8 rather than using the platform locale encoding, avoiding corruption of non-ASCII secrets on some Windows code pages.
2.15.0release notes
This package is no longer required at runtime.
2.15.0release notes
An empty section now falls back to defaults instead of raising an AttributeError.
2.15.0release notes