How to Set and Use Environment Variables in Python

Almost every Python dev has been there: you push your code, and it immediately dies in production with a nasty KeyError or a silent NoneType error because an environment variable went missing or didn't parse. Or worse, everything runs seamlessly when you test it in your terminal, but the second you hit "Run" inside your IDE, the variables just vanish into thin air. Let’s walk through why this happens under the hood and how to set things up so it never bites you again.

• Safe fetching: os.environ.get('KEY') lets you grab system values cleanly without crashing your script when something is missing.
• Local workflows: Grabbing python-dotenv lets you work with local .env files without constantly exporting stuff manually.
• Types: Always remember that environment variables are strictly strings. You'll have to cast them by hand if you need numbers or booleans.
• Process lifetime: Anything you write to os.environ inside your code dies the moment your script stops executing.

Setting System-Level Environment Variables

System-level variables exist in the operating system environment before Python even spins up. When you're running on staging or production servers, this is how you want to supply your configuration.

Windows

Temporary (valid only while this shell window stays open):

Bash

set API_KEY=mysecretkey123

Permanent (keeps working after you reopen the terminal):

Bash

setx API_KEY "mysecretkey123"

Keep in mind that setx won't update your currently open cmd or PowerShell prompts - you’ll need to restart them to see the changes take effect.

Via the GUI: Hit the Windows key, search for "Edit the system environment variables," click the "Environment Variables..." button near the bottom, and drop a new key-value pair under "User variables."

macOS and Linux

Temporary (disappears when the terminal session closes):

Bash

export API_KEY="mysecretkey123"

Permanent: Append that export command directly into your shell’s profile file, then reload it into your active shell:

Bash

# On modern macOS (which runs Zsh by default)
echo 'export API_KEY="mysecretkey123"' >> ~/.zshrc
source ~/.zshrc

# On most Linux distributions or older macOS (running Bash)
echo 'export API_KEY="mysecretkey123"' >> ~/.bashrc
source ~/.bashrc

Reading Environment Variables in Python

Python’s built-in os module handles the handshake with your underlying OS. You have two main ways to pull values out, and using the wrong one in the wrong place is usually what triggers those midnight crashes.

Accessing values through dictionary bracket syntax like os.environ['API_KEY'] makes the variable mandatory. If it isn't set, Python raises an immediate KeyError. Honestly, that strictness is actually a good thing for critical secrets like your primary database credentials - it's way better to fail loudly at startup than to stumble forward half-configured.

When you're dealing with optional settings, os.environ.get('PORT', '8080') is the friendlier tool. It gracefully hands back None if the key doesn't exist, or defaults to whatever fallback value you pass as the second argument.

Python

import os

# Fails fast with a KeyError if API_KEY isn't present - ideal for essential secrets
api_key = os.environ['API_KEY']

# Returns None or falls back cleanly to '8080' if PORT is unset - great for defaults
port = os.environ.get('PORT', '8080')

print(f"Running on port: {port}")

Before you start wiring these up in your app, just double-check that your active Python environment is up to date and pointing where you expect.

The Type Conversion Trap

Here’s the trap that catches almost everyone at least once: environment variables are always strings. If you define DEBUG=False in your shell and wrap it in bool(os.environ.get('DEBUG')), Python evaluates it as True - because in Python, any non-empty string is truthy.

Because of that quirk, you have to parse your incoming strings into real types explicitly:

Python

import os

# TRAP: This ends up True because the string "False" has a non-zero length!
debug_mode = bool(os.environ.get('DEBUG'))

# SAFE: Compare the raw string directly
debug_mode = os.environ.get('DEBUG') == 'True'

# Parsing numbers
port = int(os.environ.get('PORT', '8080'))

# Parsing lists (like comma-separated domains)
allowed_hosts = os.environ.get('ALLOWED_HOSTS', '').split(',')

Checking os.environ.get('DEBUG') == 'True' guarantees that your app only flips into debug mode when the string matches precisely, keeping you from accidentally exposing internal debug logs in your production environment.

Using .env Files for Local Development

Typing out dozens of manual exports every time you switch repositories or open a new shell gets old fast. Keeping them organized inside a local .env file saves your sanity and keeps everyone on your team on the same page.

Bash

pip install python-dotenv

Drop a .env file right into the root of your project:

Plaintext

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

Then trigger the loader right at the top of your main entry point:

Python

from dotenv import load_dotenv
import os

# Fire this before your application attempts to read any environment variables
load_dotenv()

# If you want .env entries to take precedence over your system environment:
# load_dotenv(override=True)

api_key = os.environ.get('API_KEY')
port = int(os.environ.get('PORT', '8080'))

By default, existing system variables take precedence over whatever is in your file. If you want your local file values to win out during testing, pass override=True into load_dotenv().

Never Commit Your .env File

Make sure .env is sitting inside your .gitignore file from day one:

Plaintext

# .gitignore
.env

To make onboarding painless for other contributors without leaking sensitive values, build a .env.example file that tracks the keys with blank placeholders, and check that into git instead:

Plaintext

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

Whenever someone clones down the repo, they simply copy .env.example over to .env and plug in their local values. If you like keeping your local Python dependencies isolated and predictable alongside your config files, managing your virtual environments via Conda environments pairs really cleanly with this setup.

Advanced Configuration with Pydantic

When your codebase grows, writing boilerplate type-casting for dozens of individual variables gets messy and error-prone. Pydantic’s BaseSettings takes care of the type parsing and schema validation automatically.

Bash

pip install pydantic-settings

Python

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 comes back as a true int, settings.debug as a boolean
print(settings.port)  # 8080

Under the hood, Pydantic pulls in your environment variables, converts strings into their assigned types, and raises an informative ValidationError immediately at startup if anything is missing or malformed. Plus, you get clean autocomplete across your entire codebase instead of sprinkling loose string lookups everywhere.

Understanding Process Scope

It's helpful to remember that modifying os.environ inside your running Python script will not change your actual operating system variables. The OS treats each process as an isolated box; once your Python interpreter exits, any values it set disappear with it.

Python

import os

os.environ['TEMP_DIR'] = '/tmp'
print(os.environ.get('TEMP_DIR'))  # Prints /tmp while the script runs

# As soon as this script finishes, TEMP_DIR is gone from your shell

If your code launches external scripts or CLI tools via subprocesses, you can pass variables downstream safely by creating an explicit copy with os.environ.copy():

Python

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 hands the child process a cloned dictionary with your extra keys included, giving the subprocess what it needs without polluting your main process or touching your system-wide environment.

Common Pitfalls and Troubleshooting

"It runs in my terminal, but breaks when I click Run/Debug in my editor." Your shell loads your .zshrc or .bashrc automatically when it launches, but IDE debuggers often spin up inside a sterile, stripped-down environment. You can patch this in VS Code by pointing to your local environment file in .vscode/launch.json:

JSON

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

If you're using PyCharm, open your Run/Debug Configurations, pick your active target, and set the file path inside the "EnvFile" section directly.

load_dotenv() runs without throwing errors, but my variables are still None. Nine times out of ten, this happens because you executed the script from a directory different from where the .env file actually sits. You can resolve the path cleanly relative to your script file:

Python

from dotenv import load_dotenv
from pathlib import Path

env_path = Path(__file__).parent / '.env'
load_dotenv(dotenv_path=env_path)

pip install dotenv broke your project imports. That installs a completely separate, abandoned package rather than the tool you want. Run pip uninstall dotenv, and then run pip install python-dotenv. If your package manager is throwing unrelated packaging warnings along the way, upgrading pip usually clears out those odd dependency glitches.

Keep in mind that while .env files are fantastic for day-to-day local development, you shouldn't rely on raw files on disk for production. In staging or live environments, lean on dedicated secret stores like AWS Secrets Manager, HashiCorp Vault, or Doppler - they take care of automatic rotation, fine-grained access control, and audit logs that a static file simply can't offer.