{"id":141,"library":"pydantic-settings","title":"Pydantic Settings","description":"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).","status":"active","version":"2.13.1","language":"python","source_language":"en","source_url":"https://github.com/pydantic/pydantic-settings","tags":["pydantic","settings","configuration","env","dotenv","python"],"install":[{"cmd":"pip install pydantic-settings","lang":"bash","label":"Python"},{"cmd":"pip install 'pydantic-settings[toml]'","lang":"bash","label":"Python (with TOML file support)"},{"cmd":"pip install 'pydantic-settings[yaml]'","lang":"bash","label":"Python (with YAML file support)"}],"dependencies":[{"reason":"Requires pydantic >= 2.0. Will not work with pydantic v1.","package":"pydantic","optional":false},{"reason":"Required for .env file loading. Installed automatically with pydantic-settings.","package":"python-dotenv","optional":false}],"imports":[{"note":"BaseSettings was removed from pydantic core in V2. 'from pydantic import BaseSettings' raises ImportError. Must install pydantic-settings separately and import from pydantic_settings.","wrong":"from pydantic import BaseSettings","symbol":"BaseSettings","correct":"from pydantic_settings import BaseSettings, SettingsConfigDict\n\nclass Settings(BaseSettings):\n    model_config = SettingsConfigDict(env_file='.env', env_file_encoding='utf-8')\n\n    api_key: str\n    debug: bool = False\n\nsettings = Settings()"},{"note":"Inner Config class is pydantic V1 style. Use model_config = SettingsConfigDict(...) in V2.","wrong":"class Settings(BaseSettings):\n    class Config:\n        env_file = '.env'\n        env_prefix = 'APP_'","symbol":"SettingsConfigDict","correct":"from pydantic_settings import BaseSettings, SettingsConfigDict\n\nclass Settings(BaseSettings):\n    model_config = SettingsConfigDict(\n        env_file='.env',\n        env_prefix='APP_',\n        case_sensitive=False\n    )\n    api_key: str"}],"quickstart":{"code":"from pydantic_settings import BaseSettings, SettingsConfigDict\n\nclass Settings(BaseSettings):\n    model_config = SettingsConfigDict(\n        env_file='.env',\n        env_file_encoding='utf-8',\n        extra='ignore'  # ignore unknown env vars\n    )\n\n    api_key: str\n    debug: bool = False\n    port: int = 8000\n\n# reads from env vars and .env file\nsettings = Settings()\nprint(settings.api_key)","lang":"python","description":"Minimal BaseSettings loading from .env file with pydantic-settings 2.x."},"warnings":[{"fix":"pip install pydantic-settings; from pydantic_settings import BaseSettings","message":"'from pydantic import BaseSettings' raises ImportError in pydantic V2. BaseSettings moved to separate pydantic-settings package.","severity":"breaking","affected_versions":"pydantic >= 2.0"},{"fix":"Verify .env file exists before startup or use extra='forbid' to catch missing required fields early.","message":"If 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.","severity":"gotcha","affected_versions":"all"},{"fix":"Expected behavior — documented priority order: init args > env vars > .env file > defaults.","message":"Environment variables take precedence over .env file values. If the same variable is set in both the shell environment and .env, the shell value wins.","severity":"gotcha","affected_versions":"all"},{"fix":"Pass _env_file='.env' directly to CliApp.run(Settings, _env_file='.env') as workaround, or pin to 2.12.0.","message":"env_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.","severity":"gotcha","affected_versions":"2.13.0, 2.13.1"},{"fix":"class SubModel(BaseModel): ... — not BaseSettings.","message":"Nested settings via env_nested_delimiter require sub-models to inherit from pydantic.BaseModel, not BaseSettings.","severity":"gotcha","affected_versions":"all"},{"fix":"model_config = SettingsConfigDict(env_file='.env')","message":"Inner class Config: is V1 style and deprecated. Use model_config = SettingsConfigDict(...) at class level.","severity":"gotcha","affected_versions":">= 2.0"},{"fix":"model_config = SettingsConfigDict(env_file='.env', env_prefix='APP_')","message":"Passing settings config as constructor underscore kwargs (_env_file, _env_prefix) is deprecated. Use model_config = SettingsConfigDict(...) instead.","severity":"deprecated","affected_versions":">= 2.0"}],"env_vars":null,"last_verified":"2026-05-12T08:27:09.829Z","next_check":"2026-06-24T00:00:00.000Z","problems":[{"fix":"First, install the `pydantic-settings` package: `pip install pydantic-settings`. Then, change your import statement from `from pydantic import BaseSettings` to `from pydantic_settings import BaseSettings`.","cause":"This error occurs because in Pydantic v2, `BaseSettings` was moved from the main `pydantic` package to a new, separate package called `pydantic-settings`.","error":"PydanticImportError: `BaseSettings` has been moved to the `pydantic-settings` package."},{"fix":"Install the `pydantic-settings` package using pip: `pip install pydantic-settings`.","cause":"This error indicates that the `pydantic-settings` library has not been installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'pydantic_settings'"},{"fix":"Ensure that the required environment variable is set or correctly defined in your `.env` file. If using a `.env` file, specify its path explicitly in `model_config` (e.g., `model_config = SettingsConfigDict(env_file='.env')`) and provide an absolute path if your script is run from a different directory than the `.env` file (e.g., `env_file=os.path.join(os.path.dirname(__file__), '.env')`).","cause":"This validation error typically means that a required field in your `BaseSettings` model is not receiving a value, often because the associated environment variable or `.env` file entry is missing or the `.env` file is not being loaded correctly.","error":"pydantic_core._pydantic_core.ValidationError: 1 validation error for Settings\\nfield_name\\n  Field required [type=missing, input_value={}, input_type=dict]"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"toml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.45,"mem_mb":12.1,"disk_size":"28.5M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"yaml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.45,"mem_mb":12.1,"disk_size":"30.6M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":12.1,"disk_size":"28.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"toml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.31,"mem_mb":12.1,"disk_size":"28M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"yaml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.32,"mem_mb":12.1,"disk_size":"31M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.32,"mem_mb":12.1,"disk_size":"28M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"toml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.72,"mem_mb":13.4,"disk_size":"31.9M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"yaml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.69,"mem_mb":13.4,"disk_size":"33.5M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.69,"mem_mb":13.4,"disk_size":"31.1M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"toml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.56,"mem_mb":13.4,"disk_size":"32M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"yaml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.55,"mem_mb":13.4,"disk_size":"34M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.56,"mem_mb":13.4,"disk_size":"31M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"toml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.83,"mem_mb":13.3,"disk_size":"23.5M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"yaml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.81,"mem_mb":13.3,"disk_size":"25.1M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.79,"mem_mb":13.3,"disk_size":"22.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"toml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.8,"mem_mb":13.3,"disk_size":"23M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"yaml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.76,"mem_mb":13.3,"disk_size":"26M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.77,"mem_mb":13.3,"disk_size":"22M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"toml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.74,"mem_mb":13.3,"disk_size":"23.2M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"yaml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.76,"mem_mb":13.3,"disk_size":"24.8M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.73,"mem_mb":13.3,"disk_size":"22.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"toml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.7,"mem_mb":13.3,"disk_size":"23M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"yaml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.7,"mem_mb":13.3,"disk_size":"25M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.7,"mem_mb":13.3,"disk_size":"22M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"toml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.39,"mem_mb":11.2,"disk_size":"27.9M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"yaml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.39,"mem_mb":11.2,"disk_size":"30.0M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.41,"mem_mb":11.2,"disk_size":"27.8M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"toml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.38,"mem_mb":11.2,"disk_size":"28M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"yaml","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.36,"mem_mb":11.2,"disk_size":"30M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.36,"mem_mb":11.2,"disk_size":"27M"}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}