How to Set and Use Environment Variables in Python

Getting a KeyError or a silent NoneType crash in production usually means an environment variable failed to load or parse correctly. Debugging why a variable works in your terminal but disappears when you run the script through your IDE is a frustrating loop, and here is what is actually happening, and how to fix all of it.

Setting System-Level Environment Variables

System-level variables are set at the OS level, before your Python script ever runs. This is the standard approach for production servers.

Windows

Temporary (current session only):

set API_KEY=mysecretkey123

Permanent (survives terminal restarts):

setx API_KEY "mysecretkey123"

You must restart any open terminals after setx for the new variable to load.

GUI: Search for "Edit the system environment variables" in the Start menu, click "Environment Variables...", then add a new entry under "User variables".

macOS and Linux

Temporary (current session only):

export API_KEY="mysecretkey123"

Permanent: Add the export line to your shell config file and reload it:

# For Zsh (default on modern macOS)
echo 'export API_KEY="mysecretkey123"' >> ~/.zshrc
source ~/.zshrc
# For Bash (Linux, older macOS)
echo 'export API_KEY="mysecretkey123"' >> ~/.bashrc
source ~/.bashrc

Reading Environment Variables in Python

The built-in os module handles the core interaction with your operating system. You have two primary ways to fetch a value, and picking the wrong one causes immediate crashes.

Using os.environ['API_KEY'] forces the application to find that exact key. If the key is missing, Python throws a fatal KeyError. This strictness is effective for critical secrets like database passwords, where you want the app to fail at startup rather than run with missing credentials.

For non-critical configurations, os.environ.get('PORT', '8080') is the safer choice. It returns None if the variable is missing, or falls back to the default value you provide as the second argument.

import os
# Crashes with KeyError if API_KEY is not set -- use for required secrets
api_key = os.environ['API_KEY']
# Returns None (or your default) if PORT is not set -- use for optional config
port = os.environ.get('PORT', '8080')
print(f"Running on port: {port}")

Before testing these variations, make sure your Python installation is up to date.

The Type Conversion Trap

Environment variables are absolutely always strings. Setting a variable as DEBUG=False in your system and reading it directly in Python evaluates to a True boolean, because any non-empty string is truthy in Python.

You must manually convert string values to their proper types:

import os
# WRONG: this is always True because "False" is a non-empty string
debug_mode = bool(os.environ.get('DEBUG'))
# CORRECT: explicit string comparison
debug_mode = os.environ.get('DEBUG') == 'True'
# For integers
port = int(os.environ.get('PORT', '8080'))
# For lists (comma-separated values)
allowed_hosts = os.environ.get('ALLOWED_HOSTS', '').split(',')

Evaluating os.environ.get('DEBUG') == 'True' ensures that only an exact string match activates debugging mode, preventing accidental truthy evaluations that expose sensitive data in production logs.

Using .env Files for Local Development

Managing dozens of variables directly in your terminal gets messy fast. Storing them in a local .env file keeps your workspace organized and ensures consistent configurations across your team.

pip install python-dotenv

A flowchart showing the 3-step process of using a .env file in Python: 1. The .env file is created with keys and values. 2. load_dotenv() is called to integrate it. 3. os.getenv() is used to access the values.

Create a .env file in your project root:

# .env
API_KEY=mysecretkey123
DATABASE_URL=postgres://user:pass@localhost/mydb
DEBUG=True
PORT=8080

Then load it at the very top of your main script:

from dotenv import load_dotenv
import os
# Call this before any os.environ.get() calls
load_dotenv()
# To override existing system variables with .env values:
# load_dotenv(override=True)
api_key = os.environ.get('API_KEY')
port = int(os.environ.get('PORT', '8080'))

If you need values from your .env file to override existing system variables, pass override=True. Without that flag, system-level variables always win.

Never Commit Your .env File

Add .env to your .gitignore immediately:

# .gitignore
.env

To help teammates know which variables are needed, create a .env.example file that lists keys without values, and commit that instead:

# .env.example
API_KEY=
DATABASE_URL=
DEBUG=
PORT=

New team members copy .env.example to .env and fill in their local values. For a consistent local Python setup that pairs well with this workflow, Conda environments give you isolated per-project dependency management alongside your .env files.

Advanced Configuration with Pydantic

Manually casting strings across a large codebase is error-prone. Pydantic's BaseSettings automates validation and type conversion entirely.

pip install pydantic-settings

from pydantic_settings import BaseSettings
class Settings(BaseSettings):
    api_key: str
    port: int = 8080
    debug: bool = False
    database_url: str
    class Config:
        env_file = ".env"
settings = Settings()
# settings.port is already an int, settings.debug is already a bool
print(settings.port)  # 8080

Pydantic reads your environment variables, converts strings to your specified types, and raises a clear ValidationError at startup if a required value is missing or malformatted. Your entire configuration lives in one predictable object with full editor autocomplete.

Understanding Process Scope

Changes you make to os.environ inside your Python script do not persist after the script exits. The operating system isolates environment variables to the specific process running them.

import os
os.environ['TEMP_DIR'] = '/tmp'
print(os.environ.get('TEMP_DIR'))  # /tmp, works inside this script
# After the script exits, TEMP_DIR is completely gone from the system

When your Python code triggers subprocesses, pass variables down explicitly using os.environ.copy():

import subprocess
import os
env = os.environ.copy()
env['CUSTOM_VAR'] = 'my_value'
result = subprocess.run(['node', 'script.js'], env=env, capture_output=True)

This creates a safe duplicate of the current environment, letting you inject custom variables into the subprocess without polluting the parent process or the system environment permanently.

Common Pitfalls and Troubleshooting

Variables work in terminal but not in VS Code or PyCharm. Terminals load variables from your shell profile automatically; IDE debuggers often launch in a blank, isolated environment. Fix this by adding an envFile entry to your .vscode/launch.json:

{
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "envFile": "${workspaceFolder}/.env"
    }
  ]
}

For PyCharm: go to Run/Debug Configurations, find your run config, and set the "EnvFile" path explicitly.

load_dotenv() runs without error but variables are still missing. This happens when your script is executed from a different working directory than where the .env file lives. Build the absolute path explicitly:

from dotenv import load_dotenv
from pathlib import Path
env_path = Path(__file__).parent / '.env'
load_dotenv(dotenv_path=env_path)

pip install dotenv breaks your imports. That installs a completely different, unsupported package. The correct one is python-dotenv. Uninstall the wrong package first: pip uninstall dotenv, then run pip install python-dotenv. If pip itself is throwing errors, upgrading pip first resolves most installation issues.

When you need production-grade secret management, .env files are a development-only tool. For production, use a secrets manager (AWS Secrets Manager, HashiCorp Vault, or Doppler) that handles rotation, access control, and audit logs, which are things a plain text file cannot provide.