●Change8

Migrating to Pydantic Settings v2.11.0

Version v2.11.0 introduces 3 breaking changes. This guide details how to update your code.

Released: 9/24/2025

3
Breaking Changes
5
Migration Steps
6
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

CliSettingsSource.__init__AWSSecretsManagerSettingsSourceInitSettingsSourcemodel_configCliSettingsSourceAzureKeyVaultSettingsSource

Breaking Changes

●Issue #1

Removed parsing of command line arguments from `CliSettingsSource.__init__`. Code that relied on automatic CLI parsing must now pass arguments explicitly or use the new CLI handling API.

●Issue #2

Reverted the fix that respected `cli_parse_args` from `model_config` with `settings_customise_sources`. The previous behavior is restored, so any custom `cli_parse_args` settings will no longer be applied.

●Issue #3

Disabled `allow_abbrev` on subparsers, so abbreviated CLI options are no longer accepted.

Migration Steps

  1. 1
    If you previously relied on `CliSettingsSource` automatically parsing `sys.argv`, update your code to pass arguments explicitly or use the new CLI API.
  2. 2
    Review any custom `cli_parse_args` settings in `model_config`; they are no longer respected after the revert.
  3. 3
    If you used abbreviated CLI options, update them to full option names due to `allow_abbrev` being disabled.
  4. 4
    When using `AWSSecretsManagerSettingsSource`, you can now provide an `endpoint_url` kwarg; adjust calls if needed.
  5. 5
    Check for warnings about unused `model_config` keys and clean up configuration.

Release Summary

Pydantic Settings 2.11.0 introduces CLI serialization, root model support, and several enhancements, while removing automatic CLI argument parsing and disabling abbreviation handling, which may require migration steps.

Need More Details?

View the full release notes and all changes for Pydantic Settings v2.11.0.

View Full Changelog