Change8

Pydantic Settings

Dev Tools

Settings management using pydantic

Latest: v2.13.09 releases3 breaking changes5 common errorsView on GitHub

Release History

v2.13.014 fixes10 features
Feb 16, 2026

This release introduces significant enhancements to CLI argument handling, deep merging for config sources, and improved support for cloud secret managers like AWS and GCP. Several bug fixes address issues related to environment variable loading and alias resolution.

v2.12.0Breaking7 features
Nov 10, 2025

pydantic-settings 2.12 introduces enum kebab‑case support, a new NestedSecretsSettings source, updated source ordering, and adds Python 3.14 support while dropping Python 3.9.

v2.11.0Breaking6 fixes9 features
Sep 24, 2025

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.

2.10.11 fix
Jun 24, 2025

Version 2.10.1 addresses an UnboundLocalError in the internal field‑name replacement helper and cleans up a broken documentation reference.

2.10.08 fixes6 features
Jun 21, 2025

pydantic‑settings 2.10.0 adds YAML nested‑key loading, case‑sensitive secret manager options, a new `cli_shortcuts` flag, and numerous bug fixes and dependency updates.

v2.9.12 fixes
May 6, 2025

pydantic-settings 2.9.1 includes bug fixes for ConfigFileSourceMixing exposure and a typo in the GCP secret manager error message.

v2.9.0Breaking5 fixes10 features
Apr 18, 2025

pydantic-settings v2.9.0 drops Python 3.8, refactors the sources module, adds secret manager integrations and several CLI enhancements, while fixing documentation typos and updating the pydantic core dependency.

v2.8.13 fixes
Feb 27, 2025

Patch release 2.8.1 fixes init source alias resolution and reverts recent breaking changes to `BaseSettings.__init__`.

v2.8.02 fixes3 features
Feb 24, 2025

Version 2.8.0 adds optional/variadic CLI arguments, a new `env_nested_max_split` setting, async CLI methods, and fixes type‑signature and env‑delimiter issues.

Common Errors

ValidationError2 reports

ValidationError in pydantic-settings often arises when a setting defined in your BaseSettings model lacks a default value and is not provided through environment variables or other configuration sources. To fix this, ensure all required settings have either a default value assigned directly in the model definition (e.g., `setting_name: str = "default_value"`) or are populated via environment variables during runtime. Consider using `field(default=...)` from pydantic for more complex default value assignments.

JSONDecodeError1 report

JSONDecodeError in pydantic-settings often arises when environment variables expected to contain JSON (like secrets) are improperly formatted or contain invalid JSON syntax. To fix this, ensure the environment variable holds a valid JSON string; use a JSON validator tool before setting the variable or consider encoding the data differently if strict JSON format is not necessary. Verify the variable's value and type using `os.environ.get()` before pydantic tries to parse it.

UnboundLocalError1 report

The UnboundLocalError usually occurs when a variable is referenced before it's assigned a value within a specific scope, often inside a conditional block. Ensure that the variable (e.g., 'field_key') is assigned a value before being used, even if it's a default value outside the conditional. Initialize the variable at the beginning of the function/block, guaranteeing it always has a defined value.

HttpResponseError1 report

HttpResponseError in pydantic-settings often arises when attempting to access resources, like Azure Key Vault secrets, that are unavailable or inaccessible due to incorrect configurations or permissions. Ensure the requested resources exist, are enabled, and that the application has the necessary permissions (e.g., Managed Identity or Service Principal permissions) to access them. Also, verify the resource endpoint (e.g., Key Vault URL) is correct and reachable.

ModuleNotFoundError1 report

The "ModuleNotFoundError" in pydantic-settings usually arises when the `pydantic-settings` package or its dependencies haven't been installed or aren't in the Python environment's path. Resolve this by installing the package using `pip install pydantic-settings` within your active virtual environment or Conda environment. If already installed, verify that the environment is correctly activated and that the package name is spelled correctly in your import statement.

Related Dev Tools Packages

Subscribe to Updates

Get notified when new versions are released

RSS Feed