Python Configuration Management

Externalize configuration from code using environment variables and typed settings. Well-managed configuration enables the same code to run in any environment without modification.

When to Use This Skill

• Setting up a new project's configuration system

• Migrating from hardcoded values to environment variables

• Implementing pydantic-settings for typed configuration

• Managing secrets and sensitive values

• Creating environment-specific settings (dev/staging/prod)

• Validating configuration at application startup

Core Concepts

1. Externalized Configuration

All environment-specific values (URLs, secrets, feature flags) come from environment variables, not code.

2. Typed Settings

Parse and validate configuration into typed objects at startup, not scattered throughout code.

3. Fail Fast

Validate all required configuration at application boot. Missing config should crash immediately with a clear message.

4. Sensible Defaults

Provide reasonable defaults for local development while requiring explicit values for sensitive settings.

Quick Start

from pydantic_settings import BaseSettings

from pydantic import Field

class Settings(BaseSettings):

    database_url: str = Field(alias="DATABASE_URL")

    api_key: str = Field(alias="API_KEY")

    debug: bool = Field(default=False, alias="DEBUG")

settings = Settings()  # Loads from environment

Fundamental Patterns

Pattern 1: Typed Settings with Pydantic

Create a central settings class that loads and validates all configuration.

from pydantic_settings import BaseSettings

from pydantic import Field, PostgresDsn, ValidationError

import sys

class Settings(BaseSettings):

    """Application configuration loaded from environment variables."""

    # Database

    db_host: str = Field(alias="DB_HOST")

    db_port: int = Field(default=5432, alias="DB_PORT")

    db_name: str = Field(alias="DB_NAME")

    db_user: str = Field(alias="DB_USER")

    db_password: str = Field(alias="DB_PASSWORD")

    # Redis

    redis_url: str = Field(default="redis://localhost:6379", alias="REDIS_URL")

    # API Keys

    api_secret_key: str = Field(alias="API_SECRET_KEY")

    # Feature flags

    enable_new_feature: bool = Field(default=False, alias="ENABLE_NEW_FEATURE")

    model_config = {

        "env_file": ".env",

        "env_file_encoding": "utf-8",

    }

# Create singleton instance at module load

try:

    settings = Settings()

except ValidationError as e:

    print(f"Configuration error:\n{e}")

    sys.exit(1)

Import settings throughout your application:

from myapp.config import settings

def get_database_connection():

    return connect(

        host=settings.db_host,

        port=settings.db_port,

        database=settings.db_name,

    )

Pattern 2: Fail Fast on Missing Configuration

Required settings should crash the application immediately with a clear error.

from pydantic_settings import BaseSettings

from pydantic import Field, ValidationError

import sys

class Settings(BaseSettings):

    # Required - no default means it must be set

    api_key: str = Field(alias="API_KEY")

    database_url: str = Field(alias="DATABASE_URL")

    # Optional with defaults

    log_level: str = Field(default="INFO", alias="LOG_LEVEL")

try:

    settings = Settings()

except ValidationError as e:

    print("=" * 60)

    print("CONFIGURATION ERROR")

    print("=" * 60)

    for error in e.errors():

        field = error["loc"][0]

        print(f"  - {field}: {error['msg']}")

    print("\nPlease set the required environment variables.")

    sys.exit(1)

A clear error at startup is better than a cryptic None failure mid-request.

Pattern 3: Local Development Defaults

Provide sensible defaults for local development while requiring explicit values for secrets.

class Settings(BaseSettings):

    # Has local default, but prod will override

    db_host: str = Field(default="localhost", alias="DB_HOST")

    db_port: int = Field(default=5432, alias="DB_PORT")

    # Always required - no default for secrets

    db_password: str = Field(alias="DB_PASSWORD")

    api_secret_key: str = Field(alias="API_SECRET_KEY")

    # Development convenience

    debug: bool = Field(default=False, alias="DEBUG")

    model_config = {"env_file": ".env"}

Create a .env file for local development (never commit this):

# .env (add to .gitignore)

DB_PASSWORD=local_dev_password

API_SECRET_KEY=dev-secret-key

DEBUG=true

Pattern 4: Namespaced Environment Variables

Prefix related variables for clarity and easy debugging.

# Database configuration

DB_HOST=localhost

DB_PORT=5432

DB_NAME=myapp

DB_USER=admin

DB_PASSWORD=secret

# Redis configuration

REDIS_URL=redis://localhost:6379

REDIS_MAX_CONNECTIONS=10

# Authentication

AUTH_SECRET_KEY=your-secret-key

AUTH_TOKEN_EXPIRY_SECONDS=3600

AUTH_ALGORITHM=HS256

# Feature flags

FEATURE_NEW_CHECKOUT=true

FEATURE_BETA_UI=false

Makes env | grep DB_ useful for debugging.

Advanced Patterns

Pattern 5: Type Coercion

Pydantic handles common conversions automatically.

from pydantic_settings import BaseSettings

from pydantic import Field, field_validator

class Settings(BaseSettings):

    # Automatically converts "true", "1", "yes" to True

    debug: bool = False

    # Automatically converts string to int

    max_connections: int = 100

    # Parse comma-separated string to list

    allowed_hosts: list[str] = Field(default_factory=list)

    @field_validator("allowed_hosts", mode="before")

    @classmethod

    def parse_allowed_hosts(cls, v: str | list[str]) -> list[str]:

        if isinstance(v, str):

            return [host.strip() for host in v.split(",") if host.strip()]

        return v

Usage:

ALLOWED_HOSTS=example.com,api.example.com,localhost

MAX_CONNECTIONS=50

DEBUG=true

Pattern 6: Environment-Specific Configuration

Use an environment enum to switch behavior.

from enum import Enum

from pydantic_settings import BaseSettings

from pydantic import Field, computed_field

class Environment(str, Enum):

    LOCAL = "local"

    STAGING = "staging"

    PRODUCTION = "production"

class Settings(BaseSettings):

    environment: Environment = Field(

        default=Environment.LOCAL,

        alias="ENVIRONMENT",

    )

    # Settings that vary by environment

    log_level: str = Field(default="DEBUG", alias="LOG_LEVEL")

    @computed_field

    @property

    def is_production(self) -> bool:

        return self.environment == Environment.PRODUCTION

    @computed_field

    @property

    def is_local(self) -> bool:

        return self.environment == Environment.LOCAL

# Usage

if settings.is_production:

    configure_production_logging()

else:

    configure_debug_logging()

Pattern 7: Nested Configuration Groups

Organize related settings into nested models.

from pydantic import BaseModel

from pydantic_settings import BaseSettings

class DatabaseSettings(BaseModel):

    host: str = "localhost"

    port: int = 5432

    name: str

    user: str

    password: str

class RedisSettings(BaseModel):

    url: str = "redis://localhost:6379"

    max_connections: int = 10

class Settings(BaseSettings):

    database: DatabaseSettings

    redis: RedisSettings

    debug: bool = False

    model_config = {

        "env_nested_delimiter": "__",

        "env_file": ".env",

    }

Environment variables use double underscore for nesting:

DATABASE__HOST=db.example.com

DATABASE__PORT=5432

DATABASE__NAME=myapp

DATABASE__USER=admin

DATABASE__PASSWORD=secret

REDIS__URL=redis://redis.example.com:6379

Pattern 8: Secrets from Files

For container environments, read secrets from mounted files.

from pydantic_settings import BaseSettings

from pydantic import Field

from pathlib import Path

class Settings(BaseSettings):

    # Read from environment variable or file

    db_password: str = Field(alias="DB_PASSWORD")

    model_config = {

        "secrets_dir": "/run/secrets",  # Docker secrets location

    }

Pydantic will look for /run/secrets/db_password if the env var isn't set.

Pattern 9: Configuration Validation

Add custom validation for complex requirements.

from pydantic_settings import BaseSettings

from pydantic import Field, model_validator

class Settings(BaseSettings):

    db_host: str = Field(alias="DB_HOST")

    db_port: int = Field(alias="DB_PORT")

    read_replica_host: str | None = Field(default=None, alias="READ_REPLICA_HOST")

    read_replica_port: int = Field(default=5432, alias="READ_REPLICA_PORT")

    @model_validator(mode="after")

    def validate_replica_settings(self):

        if self.read_replica_host and self.read_replica_port == self.db_port:

            if self.read_replica_host == self.db_host:

                raise ValueError(

                    "Read replica cannot be the same as primary database"

                )

        return self

Best Practices Summary

• Never hardcode config - All environment-specific values from env vars

• Use typed settings - Pydantic-settings with validation

• Fail fast - Crash on missing required config at startup

• Provide dev defaults - Make local development easy

• Never commit secrets - Use .env files (gitignored) or secret managers

• Namespace variables - DB_HOST, REDIS_URL for clarity

• Import settings singleton - Don't call os.getenv() throughout code

• Document all variables - README should list required env vars

• Validate early - Check config correctness at boot time

• Use secrets_dir - Support mounted secrets in containers