Managing Secrets with .env Files in Python Projects

Use python-dotenv to load environment variables from a .env file, and learn the rules and patterns that keep your secrets off GitHub permanently.

A .env file is a plain text file that lives in your project root and holds all of your environment variables in one place. Instead of typing export commands every time you open a terminal, you write your configuration values once and let the python-dotenv library load them automatically at the start of your program. This approach is standard across the Python ecosystem — you’ll see it in FastAPI projects, data science notebooks, and production services alike.

Basic setup

1. Install python-dotenv

   pip install python-dotenv
   
2. Create your .env file

   Create a file named .env in your project root. No extension — just .env:

   # .env
   API_KEY=sk-1234567890abcdef
   DATABASE_URL=sqlite:///myapp.db
   DEBUG=True
   
3. Load it in Python

   from dotenv import load_dotenv
   import os
   
   # Load the .env file — call this early, before reading any variables
   load_dotenv()
   
   # Now read your variables normally
   api_key = os.environ.get("API_KEY")
   debug   = os.environ.get("DEBUG")
   
   print(f"API Key: {api_key}")
   print(f"Debug mode: {debug}")
   

That’s all there is to it. Much easier than managing export commands.

Critical rule: add .env to .gitignore

Never commit your .env file. It contains real secrets. Add it to .gitignore before your very first commit — once a secret is in your Git history, it’s there forever even if you delete the file later.

# .gitignore
.env
.venv/
__pycache__/

Complete real-world example

Here’s a realistic pattern you’ll use when working with APIs:

# app.py
from dotenv import load_dotenv
import os
import requests

# Load environment variables at the top of the file
load_dotenv()

# Get the API key — fail early if it's missing
API_KEY = os.environ.get("OPENAI_API_KEY")

if not API_KEY:
    print("Error: OPENAI_API_KEY is not set in your .env file")
    exit(1)

# Use the key safely — it never appears in your source code
headers = {"Authorization": f"Bearer {API_KEY}"}
# Make your API calls...

Your .env file for this project:

# .env
OPENAI_API_KEY=sk-your-actual-key-here
MODEL=gpt-3.5-turbo
MAX_TOKENS=100

Show others what variables they need

Create a companion file called .env.example — this one you do commit to Git:

# .env.example
OPENAI_API_KEY=your-api-key-here
MODEL=gpt-3.5-turbo
MAX_TOKENS=100

This file documents exactly what variables a new contributor needs to set up, without exposing any real values. It’s a standard convention in open-source Python projects.

Rules for .env files

• One variable per line
• No spaces around =
• No quotes (unless the value itself contains spaces)
• Use # for comments
• Names should be UPPERCASE

Common patterns

# API Keys
OPENAI_API_KEY=sk-...
GITHUB_TOKEN=ghp_...

# Database
DATABASE_URL=sqlite:///local.db

# Application settings
DEBUG=True
PORT=8000
LOG_LEVEL=INFO

Quick tips

1. Load early — Call load_dotenv() at the very top of your entry-point script, before any other imports that might read environment variables
2. Use defaults — os.environ.get("PORT", "8000") keeps your app running even when a variable isn’t set
3. Check your .gitignore — Verify .env is listed before every new project’s first push
4. Keep it focused — Only put values in .env that genuinely change between environments or need to stay secret

What’s next?

You now know how to manage secrets safely. Ready for modern Python tooling with uv?

Modern Python

Next-level Python dependency management