Registry / serialization / pydantic-settings

pydantic-settings

library2.15.0pypypi✓ verified 26d ago

Settings management using Pydantic. Provides BaseSettings for loading config from environment variables, .env files, and secrets files with full type validation. Extracted from pydantic core into a separate package in V2. Current version is 2.13.1 (Feb 2026).

serialization auth-security

pip install pydantic-settings

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PYDANTIC-SETTINGS

pydantic-settings

serializationpythonv2.15.0

Install

3.8s avg

Import

574ms

Disk

29MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.15.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 0.599s · 30.7MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 3.8s · import 0.549s · 31MB

29MB installed

● package 29MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

BaseSettings

✓ from pydantic_settings import BaseSettings

✗ from pydantic_settings import BaseSettings, SettingsConfigDict

SettingsConfigDict

✓ from pydantic_settings import SettingsConfigDict

✗ from pydantic_settings import BaseSettings, SettingsConfigDict

Minimal BaseSettings loading from .env file with pydantic-settings 2.x.

from pydantic_settings import BaseSettings, SettingsConfigDict class Settings(BaseSettings): model_config = SettingsConfigDict( env_file='.env', env_file_encoding='utf-8', extra='ignore' # ignore unknown env vars ) api_key: str debug: bool = False port: int = 8000 # reads from env vars and .env file settings = Settings() print(settings.api_key)

Debug

Known issues

breaking'from pydantic import BaseSettings' raises ImportError in pydantic V2. BaseSettings moved to separate pydantic-settings package.

fix

pip install pydantic-settings; from pydantic_settings import BaseSettings

affects: pydantic >= 2.0

gotchaIf env_file path does not exist, pydantic-settings silently ignores it with no error. Fields fall back to environment variables or defaults. Wrong .env path causes silent misconfiguration.

fix

Verify .env file exists before startup or use extra='forbid' to catch missing required fields early.

affects: all

gotchaEnvironment variables take precedence over .env file values. If the same variable is set in both the shell environment and .env, the shell value wins.

fix

Expected behavior — documented priority order: init args > env vars > .env file > defaults.

affects: all

gotchaenv_file in 2.13.x has a regression where .env files are not loaded when using CliApp.run() without debugger attached. Known issue, tracked in pydantic-settings #795.

fix

Pass _env_file='.env' directly to CliApp.run(Settings, _env_file='.env') as workaround, or pin to 2.12.0.

affects: 2.13.0, 2.13.1

gotchaNested settings via env_nested_delimiter require sub-models to inherit from pydantic.BaseModel, not BaseSettings.

fix

class SubModel(BaseModel): ... — not BaseSettings.

affects: all

gotchaInner class Config: is V1 style and deprecated. Use model_config = SettingsConfigDict(...) at class level.

fix

model_config = SettingsConfigDict(env_file='.env')

affects: >= 2.0

deprecatedPassing settings config as constructor underscore kwargs (_env_file, _env_prefix) is deprecated. Use model_config = SettingsConfigDict(...) instead.

fix

model_config = SettingsConfigDict(env_file='.env', env_prefix='APP_')

affects: >= 2.0

Upgrade

Version history

2.15.0latest on PyPI · released Aug 7, 2026

Audit

Dependencies

pydanticrequiredRequires pydantic >= 2.0. Will not work with pydantic v1.

python-dotenvrequiredRequired for .env file loading. Installed automatically with pydantic-settings.

Agent activity

103 hits · last 30 days

node

OpenAI (training)

Bingbot

Resources

githubhttps://github.com/pydantic/pydantic-settings ↗

packagehttps://pypi.org/project/pydantic-settings/ ↗

homepagehttps://docs.pydantic.dev ↗

docshttps://docs.pydantic.dev/dev-v2/concepts/pydantic_settings/ ↗

changeloghttps://github.com/pydantic/pydantic-settings/releases ↗