Managing API Keys and Config with .env Files in Python

Every real application needs configuration — API keys, database URLs, debug flags, port numbers. Hardcoding these values directly in your source code is a serious security risk: secrets become visible to anyone who reads the code, and they can accidentally end up on GitHub. The correct approach is to read configuration from environment variables, and the easiest way to manage those variables during development is a .env file.

Why Not Hardcode Configuration?

# ❌ Bad — secrets visible in source code
API_KEY = "sk-1234567890abcdef"
DATABASE_URL = "sqlite:///myapp.db"
DEBUG = True

Problems with this approach:

Secrets are exposed to anyone who reads your code.
Values may accidentally be committed to a public repository.
Every developer on the team must edit source files to use different values.
Different environments (development, testing, production) require different settings.

What Are Environment Variables?

Environment variables are key-value pairs maintained by the operating system. They are available to every program running in that environment, and your Python code simply requests them by name:

import os

api_key = os.environ.get("API_KEY")

Your code never needs to know where the value came from — it simply asks the OS.

Setting Variables Manually (macOS / Linux)

export API_KEY="sk-123456"
export DEBUG=True

import os

print(os.environ.get("API_KEY"))
print(os.environ.get("DEBUG"))

Variables set with export exist only for the current terminal session. Once the terminal closes, they disappear. Managing ten variables this way every time you open a terminal is error-prone and time-consuming.

What Is a `.env` File?

A .env file is a plain text file that stores environment variables so you only have to write them once:

# .env

API_KEY=sk-1234567890abcdef
DATABASE_URL=sqlite:///myapp.db
DEBUG=True
PORT=8000

Python cannot read .env files automatically. You need the python-dotenv package.

Setting Up python-dotenv

Install the package

pip install python-dotenv

Create your .env file

OPENAI_API_KEY=sk-your-key
MODEL=gpt-4.1
MAX_TOKENS=200

Load and read the variables

from dotenv import load_dotenv
import os

load_dotenv()  # Reads .env and loads all variables into the environment

API_KEY   = os.environ.get("OPENAI_API_KEY")
MODEL     = os.environ.get("MODEL")
MAX_TOKENS = os.environ.get("MAX_TOKENS")

print(API_KEY)
print(MODEL)
print(MAX_TOKENS)

Call load_dotenv() once at the beginning of your application, before any other code reads from the environment.

Reading Variables Safely

Prefer os.environ.get() over os.environ["KEY"]. The get() form returns None instead of crashing when a variable is missing. You can also supply a fallback default:

port = os.environ.get("PORT", "8000")   # Falls back to "8000" if PORT is missing

Complete Example

.env

OPENAI_API_KEY=sk-your-key
MODEL=gpt-4.1
MAX_TOKENS=200

app.py

from dotenv import load_dotenv
import os

load_dotenv()

API_KEY    = os.environ.get("OPENAI_API_KEY")
MODEL      = os.environ.get("MODEL")
MAX_TOKENS = os.environ.get("MAX_TOKENS")

print(API_KEY)
print(MODEL)
print(MAX_TOKENS)

Never Commit `.env` to Git

Never commit .env files to version control!A .env file typically contains API keys, database passwords, secret keys, and access tokens. Always add it to .gitignore:

.env
.venv/
__pycache__/

Instead of sharing your real .env, create a template named .env.example with placeholder values and commit that instead:

OPENAI_API_KEY=your-api-key
DATABASE_URL=sqlite:///database.db
DEBUG=True
PORT=8000

Other developers copy the template and fill in their own values:

cp .env.example .env

Recommended Project Structure

project/
│
├── .env            ← Real secrets (git-ignored)
├── .env.example    ← Template (committed to git)
├── .gitignore
├── app.py
└── requirements.txt

Best Practices

Naming conventions

Use UPPERCASE names: DATABASE_URL, API_KEY, SECRET_KEY
One variable per line
No spaces around =: write PORT=8000, not PORT = 8000
Use # comments to group related variables

Common variables to expect

# API Keys
OPENAI_API_KEY=...
GITHUB_TOKEN=...

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

# Application Settings
DEBUG=True
PORT=8000

# Authentication
SECRET_KEY=super-secret-key

# Logging
LOG_LEVEL=INFO

Quick checklist

Call load_dotenv() at the very start of your application.
Use os.environ.get() instead of hardcoding values.
Never commit .env to GitHub.
Share .env.example instead.
Keep all configuration outside your source files.

Using .env files is a standard practice in modern Python development — you’ll find it in FastAPI, Flask, Django, and virtually every other framework.

Basics

Advanced

Pydantic

Managing API Keys and Config with .env Files in Python

Why Not Hardcode Configuration?

What Are Environment Variables?

Setting Variables Manually (macOS / Linux)

What Is a `.env` File?

Setting Up python-dotenv

Reading Variables Safely

Complete Example

Never Commit `.env` to Git

Recommended Project Structure

Best Practices

​Why Not Hardcode Configuration?

​What Are Environment Variables?

​Setting Variables Manually (macOS / Linux)

​What Is a .env File?

​Setting Up python-dotenv

​Reading Variables Safely

​Complete Example

​Never Commit .env to Git

​Sharing Projects Safely

​Recommended Project Structure

​Best Practices

Why Not Hardcode Configuration?

What Are Environment Variables?

Setting Variables Manually (macOS / Linux)

What Is a `.env` File?

Setting Up python-dotenv

Reading Variables Safely

Complete Example

Never Commit `.env` to Git

Sharing Projects Safely

Recommended Project Structure

Best Practices