What Are Environment Variables? Python Absolute Beginners Tutorial

Every Python program you write runs inside an environment. That environment knows things your code doesn't — the username of whoever launched the script, the path to installed software, and any secrets or settings you've chosen to store there. Environment variables are how programs read that information without it ever appearing in the source code.

Think of environment variables as a set of named sticky notes that the operating system holds onto. Any program running on that machine can ask to read those notes. Python gives you a simple dictionary called os.environ that holds every variable currently set in the environment. You can read from it, write to it, and check whether a particular key exists — all without changing a single line of your application logic.

What Is an Environment Variable?

An environment variable is a key-value pair that lives at the operating system level, outside any specific program. The key is always a string (typically uppercase by convention), and the value is always a string too, even if it represents a number. When you start a Python script, the interpreter inherits a copy of the environment from the process that launched it — your terminal, a web server, a CI/CD runner, or whatever else called Python.

You have almost certainly seen environment variables without realizing it. On macOS and Linux, the variable PATH tells the shell where to look for executable programs. On Windows it is named the same. The variable HOME holds your home directory path. These are environment variables that the OS sets automatically. You can add your own alongside them.

The most important reason to use environment variables is to keep sensitive information out of your code. API keys, database passwords, and secret tokens should never appear in a Python file. If they do, anyone who can read your source code — including everyone on GitHub if the repository is public — can read your secrets. Environment variables provide a clean separation between configuration (which changes per environment) and code (which stays the same).

This separation is sometimes called the twelve-factor app principle for configuration: store config in the environment, not in the code. It means the same Python file can run in development on your laptop, in staging on a test server, and in production in the cloud, each with completely different credentials, and none of those credentials ever touch the source code.

Python gives you several distinct patterns for accessing environment variables, each suited to different situations. Beginners typically start with os.getenv and move to more structured approaches as their programs grow. The accordion below covers the full range — from the simplest single-line read to production-grade typed configuration.

Reading Environment Variables in Python

Python's built-in os module is all you need to get started. Import it at the top of your file, then access os.environ, which behaves like a regular Python dictionary.

import os

# Dictionary-style access — raises KeyError if the key is missing
home_dir = os.environ['HOME']
print(home_dir)

# Safer access with a default value
port = os.getenv('PORT', '8080')
print(f"Server will run on port {port}")

# Check whether a variable exists before using it
if 'DATABASE_URL' in os.environ:
    print("Database URL found.")
else:
    print("DATABASE_URL is not set.")

The difference between os.environ['KEY'] and os.getenv('KEY') matters a lot in practice. The dictionary-style access is strict: if the key is absent, Python raises a KeyError and your program stops. os.getenv is lenient: it returns None by default, or whatever fallback you pass as the second argument. For optional settings like a debug flag or a port number, os.getenv with a sensible default is the right choice. For required secrets like an API key, consider using os.environ['KEY'] so a missing variable surfaces as an error right away rather than failing silently later.

You can also iterate over os.environ just like any other dictionary, though in most real programs you will be reading specific named variables rather than looping over all of them.

import os

# Validate required variables at startup
REQUIRED = ['API_KEY', 'DATABASE_URL', 'SECRET_KEY']

missing = [var for var in REQUIRED if not os.getenv(var)]

if missing:
    raise EnvironmentError(
        f"Missing required environment variables: {', '.join(missing)}"
    )

api_key = os.environ['API_KEY']
database_url = os.environ['DATABASE_URL']

The Centralized Config Module Pattern

Rather than scattering os.getenv calls throughout your project, a more maintainable approach is a dedicated config.py that reads and validates everything in one place. The rest of your code imports named constants rather than calling os.getenv directly, which means type checkers, tests, and IDE autocomplete all work properly.

# config.py — centralized configuration module
import os
from dotenv import load_dotenv

load_dotenv()

# Collect all missing required variables in one pass
_REQUIRED = ['DATABASE_URL', 'API_KEY', 'SECRET_KEY']
_missing = [key for key in _REQUIRED if not os.getenv(key)]
if _missing:
    raise EnvironmentError(
        f"Missing required environment variables: {', '.join(_missing)}"
    )

# Typed constants — convert once, use everywhere
DATABASE_URL: str = os.environ['DATABASE_URL']
API_KEY: str      = os.environ['API_KEY']
SECRET_KEY: str   = os.environ['SECRET_KEY']
PORT: int         = int(os.getenv('PORT', '8080'))
DEBUG: bool       = os.getenv('DEBUG', 'false').lower() == 'true'
LOG_LEVEL: str    = os.getenv('LOG_LEVEL', 'INFO').upper()

# app.py — import from config, never call os.getenv here
from config import DATABASE_URL, PORT, DEBUG

print(f"Running on port {PORT}, debug={DEBUG}")
print(f"DB: {DATABASE_URL}")

This pattern means that if a variable name changes, you update one file. All type errors are caught at import time. And when writing tests, you can override os.environ before importing config to inject test values cleanly.

Using a Dataclass for Typed Configuration

For more complex projects, wrapping config in a @dataclass gives you named fields with declared types, default values, and the ability to pass the config object around as a single dependency rather than importing individual constants everywhere.

from __future__ import annotations
import os
from dataclasses import dataclass
from dotenv import load_dotenv

load_dotenv()

@dataclass(frozen=True)
class AppConfig:
    database_url: str
    api_key: str
    secret_key: str
    port: int = 8080
    debug: bool = False
    log_level: str = 'INFO'

    @classmethod
    def from_env(cls) -> AppConfig:
        missing = [
            key for key in ('DATABASE_URL', 'API_KEY', 'SECRET_KEY')
            if not os.getenv(key)
        ]
        if missing:
            raise EnvironmentError(
                f"Missing required environment variables: {', '.join(missing)}"
            )
        return cls(
            database_url=os.environ['DATABASE_URL'],
            api_key=os.environ['API_KEY'],
            secret_key=os.environ['SECRET_KEY'],
            port=int(os.getenv('PORT', '8080')),
            debug=os.getenv('DEBUG', 'false').lower() == 'true',
            log_level=os.getenv('LOG_LEVEL', 'INFO').upper(),
        )

# Create once at startup and pass to the rest of your application
config = AppConfig.from_env()

Setting Variables and Using .env Files

You can set environment variables in Python during runtime by assigning to os.environ. This is useful when you need to pass a value to a subprocess you are about to launch. The assignment only lasts for the lifetime of your Python process — it does not permanently change anything in the system.

import os

# Set a variable for this process only
os.environ['APP_ENV'] = 'development'

# Verify it was set
print(os.getenv('APP_ENV'))  # development

# Delete a variable
del os.environ['APP_ENV']
print(os.getenv('APP_ENV'))  # None

In local development, setting variables in the terminal every time you open a new session is inconvenient. The standard solution is a .env file: a plain text file in the root of your project that lists variable names and their values, one per line. The python-dotenv library reads this file and loads the values into os.environ when your application starts.

# .env file — never commit this to version control
DATABASE_URL=postgresql://localhost/mydb
API_KEY=sk-abc123supersecretkey
PORT=5000
DEBUG=true

# app.py
import os
from dotenv import load_dotenv

# Load variables from .env into os.environ
load_dotenv()

database_url = os.getenv('DATABASE_URL')
api_key      = os.getenv('API_KEY')
port         = int(os.getenv('PORT', '8080'))
debug        = os.getenv('DEBUG', 'false').lower() == 'true'

print(f"Connecting to: {database_url}")
print(f"Debug mode: {debug}")

Setting Variables in the Terminal

Before your Python script can read an environment variable, that variable has to exist in the environment. If you are not using a .env file, you set variables directly in the shell. The syntax differs by platform.

# macOS / Linux — set for the current terminal session only
export API_KEY=sk-abc123supersecretkey
export PORT=5000

# Run your script — it will inherit the variables above
python app.py

# Remove a variable from the current session
unset API_KEY

# Windows PowerShell — set for the current session only
$env:API_KEY = "sk-abc123supersecretkey"
$env:PORT = "5000"

# Run your script
python app.py

# Remove a variable
Remove-Item Env:API_KEY

On macOS and Linux you can make a variable permanent by adding the export line to your shell profile (~/.bashrc, ~/.zshrc, etc.), though this is not recommended for secrets because those files are easy to accidentally share. For secrets, always prefer a .env file or a dedicated secrets manager.

Environment Variables in Production

The .env file and python-dotenv are local development conveniences. In production — a cloud server, a container, a CI/CD pipeline — you do not use a .env file at all. Instead, you set environment variables through the platform's own configuration interface, and your Python code reads them with exactly the same os.getenv calls. The code does not change; only the source of the values changes.

Here is how the most common platforms handle it:

The Twelve-Factor App methodology holds that configuration should live in the environment, not in the code — so the same codebase can run in development, staging, and production by simply swapping the variables. (12factor.net/config)

Python Learning Summary Points

1. Environment variables are key-value pairs stored at the OS level, outside your Python code. Python reads them through the os module's os.environ dictionary or the os.getenv function.
2. All environment variable values are strings. Always convert to the appropriate type (int, bool, etc.) in your Python code rather than expecting the OS to do it.
3. Use os.environ['KEY'] when a variable is required (raises KeyError if missing) and os.getenv('KEY', 'default') when it is optional or has a safe fallback.
4. Validate all required variables at startup in a single pass. Raise one descriptive EnvironmentError listing every missing variable rather than letting your program crash one missing key at a time.
5. A .env file combined with python-dotenv is the standard pattern for managing secrets during local development. Never commit the .env file to version control.
6. Setting os.environ['KEY'] = 'value' inside Python only affects the current running process. The change disappears when the script exits.
7. Never use bool(os.getenv('FLAG')) to read boolean flags. Any non-empty string — including "false" — evaluates as truthy. Use os.getenv('FLAG', 'false').lower() == 'true' instead.
8. The .env file and python-dotenv are for local development only. In production, set variables through your hosting platform's configuration interface. Your os.getenv calls work identically either way.
9. In growing projects, consolidate all environment variable reads into a single config.py module. The rest of your code imports named constants from it rather than calling os.getenv in multiple files. This makes auditing, refactoring, and testing significantly easier.
10. A config @dataclass with a from_env() class method gives you typed, immutable configuration. Use frozen=True to prevent accidental mutation at runtime. This is the manual equivalent of what libraries like pydantic-settings automate.
11. dotenv_values() is an alternative to load_dotenv() that returns a plain dictionary without touching os.environ. Use it when you want isolated config, need to merge multiple env files, or are writing tests that should not leak variables into subprocesses.

Understanding environment variables is one of the first practical skills that separates a beginner Python program from something ready to ship. Once you separate configuration from code, you can run the same program in development, staging, and production without changing a single line — you just swap out the environment.