Mastering Environment Variables in FastAPI: Secure, Scalable Configurations

Environment variables are the indispensable behind‑the‑scenes hero of modern backend development. Whether building an MVP or deploying a production‑ready FastAPI app, managing configuration via environment variables ensures security, flexibility, and portability.

In this guide we explore a clear, scalable, production‑ready approach to handling environment variables in FastAPI using tools such as .env files, python‑dotenv, and the powerful pydantic‑settings.

🧠 Why use environment variables?

Hard‑coding credentials or settings into code is a huge security risk. Imagine pushing code with a database password to GitHub – disaster!

Using environment variables lets you:

Exclude sensitive data from version control.

Seamlessly switch between development, staging, and production environments.

Keep code clearer and more readable.

🛠️ Option 1: Basic setup with .env + python‑dotenv

This method is ideal for quick local development.

📦 Step 1: Install package

pip install python-dotenv

📄 Step 2: Create .env file in project root

DEBUG=True
DATABASE_URL=postgresql://user:pass@localhost/db
SECRET_KEY=super-secret-key

✅ Note: Never commit the .env file to Git! Add it to .gitignore .

🧬 Step 3: Load variables in code

# main.py
from dotenv import load_dotenv
import os
load_dotenv()  # Load .env into the environment
DEBUG = os.getenv("DEBUG", "False") == "True"
DATABASE_URL = os.getenv("DATABASE_URL")
SECRET_KEY = os.getenv("SECRET_KEY")

You can now safely use these variables in your FastAPI app.

🧪 Option 2: Modern approach with pydantic‑settings

This method is strongly recommended for production applications and large teams, offering type safety, validation, and default fallbacks.

📦 Step 1: Install dependency

pip install pydantic-settings

⚙️ Step 2: Create config class

# config.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    DEBUG: bool = False
    DATABASE_URL: str
    SECRET_KEY: str

    class Config:
        env_file = ".env"

settings = Settings()

⚡ Step 3: Use settings in FastAPI app

# main.py
from fastapi import FastAPI
from config import settings

app = FastAPI(debug=settings.DEBUG)

@app.get("/")
def read_root():
    return {
        "environment": "development" if settings.DEBUG else "production",
        "db": settings.DATABASE_URL,
    }

Simple, clear and type‑safe!

🚀 Switching between environments

Assume you have separate configuration files such as:

.env.development

.env.staging

.env.production

You can dynamically load the appropriate file based on an ENV variable:

# config.py
import os
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    DEBUG: bool = False
    DATABASE_URL: str
    SECRET_KEY: str

    class Config:
        env_file = f".env.{os.getenv('ENV', 'development')}"

Then set your environment:

ENV=production uvicorn main:app --host 0.0.0.0 --port 8000

📁 Recommended project structure

project/
├── app/
│   ├── main.py
│   ├── config.py
│   └── ...
├── .env.development
├── .env.production
└── requirements.txt

🛡️ Security tips

✅ Add .env* to .gitignore.

✅ In production, use deployment secrets (Docker, GitHub Actions, Heroku) instead of plain .env files.

✅ Avoid logging sensitive environment variables.

🐳 Bonus: Using environment variables in Docker

If you containerize your app, you can pass environment variables via the Dockerfile or docker‑compose.env file.

Dockerfile:

ENV DATABASE_URL=postgresql://prod_user:pass@prod/db

docker-compose.yml:

services:
  web:
    build: .
    env_file:
      - .env.production

💬 Final summary

FastAPI gives us speed, and Pydantic provides type safety. Combine them with smart environment‑variable management and your backend becomes robust and secure.