v2.15.0

Highlights

Behavior changes

• 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.
• Fields with unresolved forward references now emit a warning (#901). Settings sources can silently fail to resolve such fields; they now raise IncompleteFieldDefinitionWarning telling you to call model_rebuild(). If you have filterwarnings = error configured, this may surface as a new failure.
• Non-JSON env values for strict fields now raise ValidationError (#926) instead of a less specific error.

New features

• Show environment variable names in CLI help via 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.
• GCP: project_id can come from an earlier settings source (#878), rather than only from the constructor or GOOGLE_CLOUD_PROJECT.

Bug fixes

• Fix env vars not loading on Windows with case_sensitive=True (#894). Windows upper-cases os.environ keys, so fields raised Field required instead of picking up their values.
• Read secret files as UTF-8 instead of the platform locale encoding (#917). On Windows code pages such as cp1252 this silently corrupted non-ASCII secrets.
• Fix AliasPath on nested model fields not JSON-decoding env values (#898).
• Fix case-insensitive matching for optional nested models (#905).
• Fix dotenv extras being wrongly claimed by a complex field sharing a name prefix (#912) — e.g. dbx_token being swallowed by a db: dict field.
• Fix nested_model_default_partial_update=True corrupting discriminated unions (#876).
• Fix Secret subclasses crashing when loaded from the environment (#920).
• Fix enum names not parsing through nested annotations such as Optional[Annotated[MyEnum, ...]] with env_parse_enums=True (#910).
• An empty 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).
• GCP: skip the list_secrets call when case_sensitive=True (#862), lowering the required IAM permissions to just roles/secretmanager.secretAccessor.
• AWS: types-boto3[secretsmanager] is no longer required at runtime (#880).

Documentation

• Document JSON parsing of complex env values, plus a comma-separated-values recipe (#919).
• Recommend an async settings loading pattern (#908).
• Clarify behavior when an unprefixed value is present in a dotenv file (#895).
• Clarify environment variable helper descriptions (#867) and fix assorted typos (#904).

All changes (including dependency bumps and internal maintenance)

What's Changed

• Update documentation link for Pydantic settings by @hramezani in #863
• Bump the python-packages group with 4 updates by @dependabot[bot] in #865
• docs: clarify environment variable helper descriptions by @vip892766gma in #867
• Bump the python-packages group with 4 updates by @dependabot[bot] in #870
• Bump the python-packages group with 4 updates by @dependabot[bot] in #875
• Skip list_secrets call when case_sensitive=True by @ecerulm in #862
• GoogleSecretManagerSettingsSource: read project_id from previous sources by @ecerulm in #878
• Bump the python-packages group with 3 updates by @dependabot[bot] in #883
• fix: move SecretsManagerClient type import under TYPE_CHECKING by @gavin913-lss in #880
• Skip partial update merging for discriminated union fields by @hramezani in #876
• Support using a table header as root when reading a TOML file by @whyscream in #882
• Bump the python-packages group with 4 updates by @dependabot[bot] in #885
• Don't complain about missing table headers in a TOML file that isn't there by @whyscream in #886
• Address issues in toml table header implementation by @whyscream in #887
• Bump the python-packages group with 2 updates by @dependabot[bot] in #888
• Prevent NestedSecretsSettingsSource from following symlinks outside secrets_dir by @hramezani in #889
• Add 'Part of the Pydantic Stack' footer to README by @strawgate in #891
• Bump the python-packages group with 3 updates by @dependabot[bot] in #893
• Add support for showing environment variable names in CLI help text by @brad-alexander in #860
• Fix loading env vars on Windows with case_sensitive=True by @hramezani in #894
• Bump the github-actions group with 3 updates by @dependabot[bot] in #896
• Bump the python-packages group with 3 updates by @dependabot[bot] in #897
• Add explicit callout for the case where the unprefixed value is in dotenv by @martinky24 in #895
• Fix AliasPath on nested model fields not decoding env values (#670) by @hramezani in #898
• Support case_sensitive in InitSettingsSource and config file sources by @hramezani in #900
• Warn when using fields not fully resolved at instantiation by @Viicos in #901
• Support Traversable for json/toml/yaml config file sources (#299) by @hramezani in #902
• docs: fix typos in docs and source comments by @maxtaran2010 in #904
• Apply case-insensitive field matching to optional nested models (#903) by @hramezani in #905
• Bump boto3 from 1.43.36 to 1.43.40 in the python-packages group by @dependabot[bot] in #907
• Add PYDANTIC_SETTINGS_DEBUG for debugging settings sources (#538) by @hramezani in #906
• docs: recommend async settings loading pattern by @w3lld1 in #908
• fix: parse enum names through nested annotations by @Sanjays2402 in #910
• Fix dotenv extras being claimed by complex fields sharing a name prefix by @ritsth in #912
• Add debug logging for env_file an...

v2.14.2

What's Changed

This is a security patch release.

• Prevent NestedSecretsSettingsSource from following symlinks outside secrets_dir by @hramezani in #889
• Prepare release 2.14.2 by @hramezani in #890

Security

Fixes 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

v2.14.1

What's Changed

• Bump the python-packages group with 4 updates by @dependabot[bot] in #850
• Bump the python-packages group with 5 updates by @dependabot[bot] in #854
• Bump the github-actions group with 3 updates by @dependabot[bot] in #853
• Bump the python-packages group with 2 updates by @dependabot[bot] in #856
• Fix field named cls conflicting with classmethod parameter by @hramezani in #858
• Prepare release 2.14.1 by @hramezani in #859

Full Changelog: v2.14.0...v2.14.1

v2.14.0

What's Changed

• Fix parsing env vars into Optional Strict types by @hramezani in #792
• Fix RecursionError with mutually recursive models in CLI by @hramezani in #794
• Fix env_file from model_config ignored in CliApp.run() (#795) by @hramezani in #796
• Update dependencies by @hramezani in #798
• Add Dependabot configuration by @hramezani in #801
• Bump samuelcolvin/check-python-version from 4.1 to 5 by @dependabot[bot] in #802
• Bump actions/upload-artifact from 4 to 7 by @dependabot[bot] in #803
• Bump actions/checkout from 4 to 6 by @dependabot[bot] in #804
• Bump astral-sh/setup-uv from 5 to 7 by @dependabot[bot] in #805
• Bump actions/setup-python from 5 to 6 by @dependabot[bot] in #806
• Ignore chardet and group GitHub Actions in Dependabot by @hramezani in #808
• Bump actions/download-artifact from 4 to 8 in the github-actions group by @dependabot[bot] in #809
• Bump the python-packages group with 2 updates by @dependabot[bot] in #810
• Support reading .env files from FIFOs (e.g. 1Password Environments) by @JacobHayes in #776
• Fix AliasChoices ignored when changing provider priority by @hramezani in #813
• fix: resolve KeyError in run_subcommand for underscore field names by @bradykieffer in #799
• Bump the python-packages group with 3 updates by @dependabot[bot] in #814
• Fix Literal[numeric Enum] coercion for CLI and env vars by @m9810223 in #811
• Fix nested discriminated unions not discovered by env/CLI providers by @hramezani in #816
• Bump the python-packages group with 3 updates by @dependabot[bot] in #820
• CLI ensure env nested max split internally. by @kschwab in #821
• Bump the python-packages group with 4 updates by @dependabot[bot] in #824
• Migrate boto3-stubs to types-boto3 by @hramezani in #831
• Fix CLI not recognizing field name with validate_by_name and AliasChoices by @hramezani in #826
• Allow customisation of the dotevn setting source to filter variables by @CaselIT in #832
• Bump the python-packages group with 3 updates by @dependabot[bot] in #833
• Introduce yamlfmt by @Viicos in #836
• Bump boto3 from 1.42.82 to 1.42.83 in the python-packages group by @dependabot[bot] in #837
• Introduce zizmor by @Viicos in #838
• Fix CliPositionalArg[list[CustomType]] crash for custom types by @hramezani in #839
• Add note about Mypy plugin for BaseSettings.__init__() by @Viicos in #842
• Fix cli_ignore_unknown_args=True not working on subcommands by @hramezani in #844
• Bump the python-packages group with 4 updates by @dependabot[bot] in #847
• Fix CLI descriptions lost under python -OO by falling back to json_schema_extra by @hramezani in #843
• Prepare release 2.14.0 by @hramezani in #848

New Contributors

• @dependabot[bot] made their first contribution in #802
• @JacobHayes made their first contribution in #776
• @bradykieffer made their first contribution in #799
• @CaselIT made their first contribution in #832

Full Changelog: v2.13.1...v2.14.0

v2.13.1

What's Changed

• Fix regression for bool fields since 2.13.0 by @hramezani in #784
• Fix RecursionError with self-referential models in CliApp by @hramezani in #783
• Fix CLI parsing error for set field types since 2.13.0 (#787) by @hramezani in #788
• Fix AttributeError with nested env vars for dict fields (#785) by @hramezani in #786
• Fix JSON decoding for parameterized PEP 695 type aliases by @hramezani in #780
• v2.13.1 by @hramezani in #790

Full Changelog: v2.13.0...v2.13.1

v2.13.0

What's Changed

• fix: Deterministic alias selection when using validate_by_name by @chbndrhnns in #707
• add deep merge functionality to config file sources by @pmeier in #698
• Add support for AWS Secrets Manager VersionId parameter by @jcyamacho in #708
• bugfix: Return None for inaccessible GCP Secret Manager secrets by @zaphod72 in #712
• Bugfix for cli_kebab_case="all" and CliImplicitFlag[bool] by @Digity101 in #702
• Unpack type alisases when looking for NoDecode by @tselepakis in #695
• CliToggleFlag and CliDualFlag by @kschwab in #717
• Fix for CLI duplicate enum field values. by @kschwab in #722
• fixed load nested config from env by @Sube-py in #723
• Add non-Path files support (for example Traversable) and open files using Path.open method by @mahenzon in #724
• add one more traversable test by @mahenzon in #725
• CLI fix fox external list args. by @kschwab in #727
• fix: handle case-insensitive retrieval in GoogleSecretManagerSettingsSource by @ezwiefel in #730
• CLI test fixes for help text formatting. by @kschwab in #735
• Avoid conflicts with the NAME environment variable in WSL by @kzrnm in #747
• fix: When restoring init kwargs, use deterministic order by @chbndrhnns in #746
• Add env_prefix_target by @kzrnm in #749
• Remove (default: …) in the help message for CliToggleFlag by @kzrnm in #740
• Add support for CLI serialize styles. by @kschwab in #755
• Add support for overriding default help on CLI internal parser. by @kschwab in #758
• CLI format_help method support by @kschwab in #759
• feat(gcp): support SecretVersion annotation for per-field secret versioning by @ezwiefel in #763
• Allow snake_case_conversion with env_prefix for Azure Key Vault source by @cstarkers in #762
• fix: Only override preferred_key when no value was found by @chbndrhnns in #767
• Update deps by @hramezani in #768
• CLI coerce numeric types. by @kschwab in #769
• CLI Union Discriminator Choices in Help by @kschwab in #764
• Add nested path support for yaml_config_section (fixes #772) by @hugo-romero-mm in #773
• Prepare release 2.13.0 by @hramezani in #777

New Contributors

• @pmeier made their first contribution in #698
• @jcyamacho made their first contribution in #708
• @zaphod72 made their first contribution in #712
• @Digity101 made their first contribution in #702
• @Sube-py made their first contribution in #723
• @mahenzon made their first contribution in #724
• @kzrnm made their first contribution in #747
• @cstarkers made their first contribution in #762
• @hugo-romero-mm made their first contribution in #773

Full Changelog: v2.12.0...v2.13.0

v2.12.0

What's Changed

• Support for enum kebab case. by @kschwab in #686
• Apply source order: init > env > dotenv > secrets > defaults and pres… by @chbndrhnns in #688
• Add NestedSecretsSettings source by @makukha in #690
• Strip non-explicit default values. by @kschwab in #692
• Coerce env vars if strict is True. by @kschwab in #693
• Restore init kwarg names before returning final state dictionary. by @kschwab in #700
• Drop Python3.9 support by @hramezani in #699
• Adapt test_protected_namespace_defaults for dev. Pydantic by @musicinmybrain in #637
• Add Python 3.14 by @hramezani in #704
• Prepare release 2.12 by @hramezani in #705

New Contributors

• @chbndrhnns made their first contribution in #688

Full Changelog: v2.11.0...v2.12.0

v2.11.0

What's Changed

• CLI Serialize Support by @kschwab in #643
• Inspect type aliases to determine if an annotation is complex by @tselepakis in #644
• Revert "fix: Respect 'cli_parse_args' from model_config with settings_customise_sources (#611)" by @hramezani in #655
• Remove parsing of command line arguments from CliSettingsSource.__init__. by @trygve-baerland in #656
• turn off allow_abbrev on subparsers by @mroch in #658
• CLI Serialization Fixes by @kschwab in #649
• Fix PydanticModel type checking. by @kschwab in #659
• Avoid env_prefix falling back to env vars without prefix by @tselepakis in #648
• Warn if model_config sets unused keys for missing settings sources by @HomerusJa in #663
• Included endpoint_url kwarg in AWSSecretsManagerSettingsSource class by @adrianohrl in #664
• Fix typo ("Accesing") in the "Adding sources" docs by @deepyaman in #668
• CLI Windows Path Fix by @kschwab in #669
• Cli root model support by @kschwab in #677
• Snake case conversion in Azure Key Vault by @AndreuCodina in #680
• Make InitSettingsSource resolution deterministic by @enrico-stauss in #681
• Update deps by @hramezani in #683

New Contributors

• @tselepakis made their first contribution in #644
• @trygve-baerland made their first contribution in #656
• @mroch made their first contribution in #658
• @HomerusJa made their first contribution in #663
• @adrianohrl made their first contribution in #664
• @deepyaman made their first contribution in #668
• @enrico-stauss made their first contribution in #681

Full Changelog: 2.10.1...v2.11.0

v2.10.1

What's Changed

• Fix UnboundLocalError error in _replace_field_names_case_insensitively by @hramezani in #639
• Remove unknown file reference in documentation by @Viicos in #640
• Prepare release 2.10.1 by @hramezani in #642

Full Changelog: 2.10.0...2.10.1

v2.10.0

What's Changed

• Fix running tests when azure-keyvault-secrets is not installed by @CyberTailor in #601
• Fix running tests when google-cloud-secret-manager is not installed by @CyberTailor in #602
• Support loading a specific nested key from YAML in YamlConfigSettingsSource by @Seunghan-Jung in #603
• Fix CLI suppression for model group help by @kschwab in #604
• Fix missing DEFAULT_PATH import by @hramezani in #606
• Fix case-insensitive handling of nested aliases in EnvironmentSettingsSource by @d15ky in #608
• Azure Key Vault case insensitive support and dash-underscore translation by @d15ky in #607
• fix: Respect 'cli_parse_args' from model_config with settings_customise_sources by @karta9821 in #611
• Bump astral-sh/setup-uv by @hramezani in #612
• Update packages by @hramezani in #613
• Update README.md by @hramezani in #616
• Fix CI badge by @hramezani in #617
• Update dependencies by @hramezani in #618
• Fix coverage report by @hramezani in #619
• Fix _consume_object_or_array on unbalanced brackets in JSON strings by @andryak in #621
• add region as a parameter to aws secret manager by @barakor-vs in #622
• Expose GCP Secret Manager case sensitive option by @bellmatthewf in #626
• Update deps by @hramezani in #633
• feat: Add cli_shortcuts to CLI settings by @karta9821 in #624
• Expose AWS Secrets Manager case sensitive option by @femiadebayo in #629
• Prepare release 2.10.0 by @hramezani in #635

New Contributors

• @Seunghan-Jung made their first contribution in #603
• @d15ky made their first contribution in #608
• @karta9821 made their first contribution in #611
• @andryak made their first contribution in #621
• @barakor-vs made their first contribution in #622
• @bellmatthewf made their first contribution in #626
• @femiadebayo made their first contribution in #629

Full Changelog: v2.9.1...2.10.0