Understanding Environment Variables in Python Projects

Learn what environment variables are, why they matter for keeping secrets safe, and how to read and set them from Python using the os module.

Environment variables are named values stored at the operating system level, completely outside your application code. When your Python program runs, it can ask the OS for those values at any time — but the values themselves never appear in your source files. This separation is what makes them the right place to store anything that’s sensitive (like API keys), machine-specific (like a database URL that differs on each developer’s laptop), or likely to change between environments (like whether debug mode is on or off).

The problem they solve

# BAD — never hardcode sensitive data like this!
api_key = "sk-1234567890abcdef"   # Anyone reading this code can see it
database = "production_database"  # Can't change without editing the code

This pattern creates three problems:

• Secrets are visible in your code and Git history
• You can’t safely share your code with others
• Different machines need different settings but require code changes

How environment variables work

Environment variables live in your operating system, not in your code:

import os

# Read from the environment — nothing sensitive ever appears here
api_key  = os.environ.get("API_KEY")
database = os.environ.get("DATABASE_NAME", "default.db")

print(f"Using database: {database}")

Setting them in the terminal

You can set environment variables temporarily from the terminal:

macOS/Linux

export API_KEY=sk-1234567890abcdef
python app.py

The variable is available while that terminal session is open. Close the terminal and it’s gone — which is why .env files (covered on the next page) are a better approach for persistent configuration.

Reading environment variables in Python

import os

# Method 1: Get with a fallback default
api_key = os.environ.get("API_KEY", "demo-key")

# Method 2: Check first, then use
if "API_KEY" in os.environ:
    api_key = os.environ["API_KEY"]
else:
    print("No API key found — using demo mode")

# Method 3: Crash loudly if the variable is missing
api_key = os.environ["API_KEY"]  # Raises KeyError if not set

Method 1 (.get() with a default) is the most common in practice. Method 3 is useful when a missing variable should be treated as an unrecoverable error, such as when starting a server without its required credentials.

Common uses

• API keys — OPENAI_API_KEY, GITHUB_TOKEN, STRIPE_SECRET_KEY
• Database URLs — DATABASE_URL, REDIS_URL
• App settings — DEBUG=True, PORT=8000, LOG_LEVEL=INFO
• File paths — LOG_DIR, UPLOAD_FOLDER

Important rules

• Environment variables are always strings — if you need a number or boolean, convert them explicitly (int(os.environ.get("PORT", "8000")))
• Names are UPPERCASE by convention
• Values are machine-specific — your DATABASE_URL will be different from a teammate’s
• They don’t persist between terminal sessions unless you set them in a shell profile or use a .env file

What’s next?

Setting variables by hand every session is tedious. .env files give you a much cleaner workflow.

Using .env files

The easier way to manage environment variables