Pydantic BaseSettings for Environment Management

The Problem with Hardcoded Settings

In any real-world application, you have configuration values that change between environments:

• Database URLs: You'll use a local PostgreSQL database for development but a managed one in production.
• API Keys: Your Stripe key for testing is different from your live key.
• Debug Flags: You want DEBUG=True locally but False in production.
• Secret Keys: These should never be stored in your version control system (like Git).

Hardcoding these values is insecure and inflexible. The industry standard, inspired by the Twelve-Factor App methodology, is to store configuration in environment variables. However, environment variables are just simple strings, which means your Python code needs to:

1. Read the string value.
2. Convert it to the correct type (e.g., str to int or bool).
3. Validate that the value is correct.

This is where Pydantic's settings management shines.

Introducing pydantic-settings

FastAPI recommends using the pydantic-settings library to manage configuration. It provides a BaseSettings class that inherits all the power of Pydantic models but is specifically designed to read values from environment variables.

Let's dive into how it works.

As the documentation explains, you define your configuration as a class that inherits from BaseSettings. Pydantic then automatically and case-insensitively tries to populate the class attributes from environment variables.

Creating and Using Your First Settings Class

The following video provides a great hands-on demonstration of the core concepts. You'll see how to define a Settings class, set default values, and override them with environment variables.

Let's solidify this with a code example that mirrors what you just saw. Within your project structure from the last lesson, you'd create app/core/config.py:

# app/core/config.py

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    APP_NAME: str = "My Awesome FastAPI App"
    ADMIN_EMAIL: str
    DEBUG_MODE: bool = False




# Create a single, reusable instance of the settings
settings = Settings()

And in your main.py or a router file, you can import and use it:

# app/main.py

from fastapi import FastAPI
from app.core.config import settings

app = FastAPI()

@app.get("/info")
def get_app_info():
    return {
        "app_name": settings.APP_NAME,
        "admin_email": settings.ADMIN_EMAIL,
        "debug_mode": settings.DEBUG_MODE,
    }

To run this, you would set the required ADMIN_EMAIL environment variable:
ADMIN_EMAIL="admin@example.com" uvicorn app.main:app --reload

Notice that DEBUG_MODE would automatically be False unless you explicitly set DEBUG_MODE=True in the environment. Pydantic handles the string-to-boolean conversion for you.

Loading Settings from a .env File

Managing multiple environment variables in the command line is fine for one or two, but it quickly becomes cumbersome for local development. A common practice is to store them in a .env file (which should always be added to your .gitignore file!).

pydantic-settings can automatically read from a .env file. You just need to tell it where to look.

Here's how you'd update your config.py:

# app/core/config.py

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    APP_NAME: str = "My Awesome FastAPI App"
    ADMIN_EMAIL: str
    DEBUG_MODE: bool = False




    # This tells pydantic to load variables from a .env file
    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")

settings = Settings()

Now, you can create a .env file in your project's root directory:

# .env

APP_NAME="My Dev App"
ADMIN_EMAIL="dev@example.com"
DEBUG_MODE=True

When you run uvicorn app.main:app --reload, Pydantic will load these values automatically. The order of priority is:

1. Arguments passed directly to the Settings initializer (e.g., Settings(APP_NAME="...")).
2. Environment variables.
3. Values from the .env file.
4. Default values defined in the class.

Advanced Validation and Special Types

The real power of pydantic-settings comes from leveraging Pydantic's rich ecosystem of validation types. Since environment variables are just strings, this ensures your application receives clean, validated, and correctly-typed data from the start.

The next video segments demonstrate several powerful types you can use in your Settings class.

Here is a more robust Settings class using these types:

# app/core/config.py

from pydantic import EmailStr, PostgresDsn, Field
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):



    # Application settings
    APP_NAME: str = "My Awesome FastAPI App"
    ADMIN_EMAIL: EmailStr
    DEBUG_MODE: bool = False




    # Database settings
    DATABASE_URL: PostgresDsn




    # API keys and secrets
    SECRET_KEY: str

    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")

settings = Settings()

If you provided an invalid email for ADMIN_EMAIL or a malformed DATABASE_URL, your application would fail to start with a clear validation error—a huge benefit for catching configuration mistakes early.

The image below offers a few more advanced tips for organizing your environment variables, such as using prefixes for grouping related settings.

An Alternative: Settings as a Dependency

So far, we've created a global settings object that is imported everywhere. This works perfectly well. However, FastAPI's Dependency Injection system offers an alternative pattern that can make testing even easier.

Instead of creating the instance in config.py, we can create a dependency that yields the settings object.

Here is the pattern in practice.

First, your config.py would only define the class:

# app/core/config.py
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    APP_NAME: str = "My Awesome FastAPI App"



    # ... other settings
    model_config = SettingsConfigDict(env_file=".env")

Then, you could create a dependencies.py file or add this to your main.py:

# app/dependencies.py
from functools import lru_cache
from typing import Annotated
from fastapi import Depends
from app.core.config import Settings

@lru_cache
def get_settings():
    return Settings()




# Type alias for the dependency
AppSettings = Annotated[Settings, Depends(get_settings)]

Now, in your path operations, you inject the settings instead of importing them:

# In a router file
from app.dependencies import AppSettings

@router.get("/info")
def get_app_info(settings: AppSettings):
    return {"app_name": settings.APP_NAME}

Django Analogy: This pattern makes testing much cleaner. In Django tests, you often have to use override_settings from django.test or a similar Pytest fixture to patch the global settings object. With FastAPI's DI, you can use app.dependency_overrides to provide a different Settings object for your tests, which is a more explicit and contained approach.

Conclusion

You now have a powerful and flexible system for managing your application's configuration. This approach is not only the standard for FastAPI but also promotes best practices for security and maintainability.

Key Takeaways:

• Use pydantic-settings: Create a class inheriting from BaseSettings to define your application's configuration.
• Leverage Type Hinting: Pydantic automatically validates and converts environment variables to the types you declare, catching errors at startup.
• Use .env for Development: Configure your Settings class with model_config to read from a .env file for local development convenience. Remember to add .env to .gitignore.
• Protect Secrets: Use special types like SecretStr to prevent sensitive data from being exposed in logs or tracebacks.
• Consider Dependency Injection: For enhanced testability, consider providing your settings via a dependency decorated with @lru_cache.

Preview of the Next Lesson:

Now that we have a solid project structure and a robust configuration system, we can start building out the core logic of our application. In the next lesson, we will implement the repository pattern to decouple database logic from business logic. This is the next step in creating the clean, layered architecture we discussed previously.