How to Set and Use Environment Variables in Python (System & .env)

Environment variables are a crucial part of modern development. They are key-value pairs stored outside your code, making your application more secure and flexible.

They are used to manage sensitive data like API keys and to separate configurations (like development vs. production).

In Python, you can work with them in two main ways:

1. Accessing system-level variables (set on Windows, macOS, or Linux).
2. Using a project-specific .env file (common for local development).

This guide covers both methods from start to finish.

Why Use Environment Variables?

Using environment variables is a best practice for several key reasons:

• Security: Keep sensitive data like API keys, database passwords, and secret tokens out of your source code. This prevents them from being leaked if you share your code on a public repository like GitHub.
• Configuration: Easily manage different settings for your Development, Staging, and Production environments. Your app can use a test database in development and a live database in production, all by changing an environment variable with no code changes.
• Portability: Your code can run on any machine without modification. As long as the correct environment variables are set on that machine, the application will work as intended.

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.

Method 1: Setting System-Level Environment Variables

This method involves setting the variable directly in your operating system. This is the primary way variables are handled on production servers.

How to Set Environment Variables on Windows

You have three common ways to set a variable on Windows.

1. Temporary (Using Command Prompt)

Use the set command. This variable only lasts for the current terminal session and will be gone when you close the window.

set API_KEY=mysecretkey123

2. Permanent (Using Command Prompt)

Use the setx command. This creates a permanent variable. You must restart your terminal for the new variable to be loaded.

setx API_KEY "mysecretkey123"

3. Permanent (Using the GUI)

1. Search for Edit the system environment variables in the Start menu.
2. Click the Environment Variables... button.
3. In the User variables section, click New...
4. Enter the Variable name (e.g., API_KEY) and Variable value.
5. Click OK on all windows. You will need to restart any open terminals.

How to Set Environment Variables on macOS & Linux

For macOS and Linux, the process is terminal-based.

1. Temporary (Using the Terminal)

Use the export command. This variable only lasts for the current terminal session.

export API_KEY="mysecretkey123"

2. Permanent (Adding to your user profile)

To make a variable permanent, you must add the export command to your shell's configuration file.

• For Bash (common on Linux and older macOS), add it to the end of ~/.bashrc or ~/.bash_profile.
• For Zsh (the default on modern macOS), add it to the end of ~/.zshrc.

After saving the file, you must either restart your terminal or run source ~/.zshrc (or the file you edited) to load the new variable.

Reading System Variables in Python (os Module)

Once a variable is set at the system level, any Python script can read it using the built-in os module.

import os
# Use os.getenv() to read the variable
api_key = os.getenv("API_KEY")
if api_key:
    print(f"The API key is: {api_key}")
else:
    print("API_KEY not found.")

Expert Tip:os.getenv() vs. os.environ - os.getenv("API_KEY"): This is the safer, preferred method. If the variable doesn't exist, it returns None and your program continues without crashing. - os.environ["API_KEY"]: This method will raise a KeyError and crash your program if the API_KEY variable is not found. You should only use this if you are 100% sure the variable exists or if you're wrapping it in a try...except block.

Method 2: Using a Project-Based .env File

This is the most common method for managing variables in your local development environment. A .env file is a simple text file you place in your project's root directory to store variables specific only to that project.

Step 1: Install the python-dotenv Library

Python doesn't read .env files by default. You need a helper library. The most popular one is python-dotenv.

Install it using pip:

pip install python-dotenv

Step 2: Create Your .env File

In the root folder of your project (the same place as your Python script), create a new file named exactly .env (starting with a dot, no name before it).

Inside this file, add your variables in the KEY=VALUE format:

# .env file
API_KEY=mysecretkey123
DATABASE_PASSWORD=supersecretpassword
DEBUG_MODE=True

Step 3: Load and Use the .env File in Python

Now, in your Python code, you first need to load the file, which adds its contents to the environment. Then you read the variables just like you did before.

from dotenv import load_dotenv
import os
# This line reads the .env file and loads the variables
load_dotenv()
# Now you can access the variables using os.getenv()
secret_key = os.getenv("API_KEY")
db_pass = os.getenv("DATABASE_PASSWORD")
print(f"Your secret key is: {secret_key}")
print(f"Your database password is: {db_pass}")

Notice that after load_dotenv() runs, you still use os.getenv() to read the variables. The python-dotenv library simply makes the values from the file available to the os module.

Critical Security Warning: Using .gitignore

You must never commit your .env file to Git (or any version control system). If you do, your secret keys will be uploaded to GitHub or GitLab, where anyone can see them.

To prevent this, you must add the file name to your .gitignore file. This tells Git to ignore the file.

Your .gitignore file should include:

# .gitignore
# Ignore the environment variables file
.env

Expert Advice: How to Share Settings with Your Team How do you tell your team which variables are needed? You create a file named .env.example. This file lists the keys but not the values. Your .env.example file would look like this:

# .env.example
API_KEY=
DATABASE_PASSWORD=
DEBUG_MODE=

You commit the .env.example file to Git. New team members can then copy this file, rename it to .env, and fill in their own local values without the secrets ever being committed to Git.

System Variable vs. .env File? Which to Use When?

Here’s a simple breakdown of which method to choose.

Use System-Level Variables for:

• Production and Staging servers.
• Server environments (like Docker, Kubernetes, Heroku, or AWS) where variables are set globally by the system.

Use .env Files for:

• Local development.
• Making it easy for new developers to get started (using the .env.example file).
• Quickly changing project settings on your own machine without affecting the whole system.