How to Set Environment Variables in Python (Step-by-Step)

There’s nothing wrong with the regular Python variables you know and love. They hang around your scripts, represent values as needed, and don’t really need much more of your attention. But some variables? Some variables are destined for greater things. They have bigger ambitions and deserve your respect as they graduate to environment variables.

Jokes aside, you can expect to learn all about environment variables in this beginner-friendly article. We’ll cover what environment variables are, how you can access them in your Python scripts, and how you can set them up in three different ways. You’ll also get a look at several extensions such as how environment variables work in production environments and how you can more safely manage sensitive data like credentials and API keys.

What is an Environment Variable?

An environment variable is a key-value pair that you’ll store outside of your application’s code. It’s configuration information that programs can access from their operating environment. Commonly, you’ll store paths (PATH), database URLs (DATABASE_URL), and credentials such as API keys (API_KEY) as environment variables.

Environment variables are typically strings. They allow you to separate configuration information from your source code. This benefits you in a variety of ways:

• The same application code can use different values in development, testing, and production.

• Multiple applications can access the same configuration variables without retyping them.

• You can keep sensitive information private if you want to share your code publicly on GitHub, for example.

Environment Variables in Python

The Python variables you’re accustomed to exist within the program itself. Environment variables in Python usually aren’t like that. They’re part of your process environment and live outside of your Python code.

When working with Python environment variables, os is the main module you need. Just make sure to add import os to the beginning of your script. The os module provides os.environ. It’s a mapping object that allows you to look up environment variables that are currently available to you.

To distinguish between Python variables and environment variables in Python, consider getting a simple API URL. This is code demonstrates regularly defining variables:

api_url = "https://example.com"

But after loading Python’s os module, this is how you might get the same information from an environment variable:

import os api_url = os.environ["API_URL"]

This code behaves differently because instead of hard-coding the URL, it relies on os.environ to find the value associated with the "API_URL" key. Also note that Python stores and returns environment variables as strings that you can go on to use elsewhere in your code.

In addition to accessing environment variables, you can also use Python code to set environment variables from within an application. Your current application as well as any program it starts have access to variables set up this way. However, environment variables you create from within Python are usually temporary. These environment variables exist only until your current application and programs launched from it end.

Python: Setting Environment Variables Temporarily

To set environment variables in Python programs, assign each as a key-value pair, similarly to how you add dictionary data. For example, you might create and retrieve an environment variable for your API key like the following code:

import os os.environ["API_KEY"] = "my_key123" print(os.environ["API_KEY"]) # Expected result:# my_key123

The keys and values must be only strings, but assuming you’ve provided valid information, your program immediately has access to this data. Additionally, programs launched from your code can also use these variables.

Creating environment variables in Python programs does not, however, permanently change your operating system environment. They apply to only the current process and any child process it starts.

You may find this style of environment variable helpful for testing or setting temporary configurations. But if you want to access an environment variable after your program ends or to give multiple independent programs access, you’ll need to define it outside of your Python script.

Setting Environment Variables Permanently

If you need an environment variable set permanently rather than just for the duration of your program, you can define it outside of Python. The method you’ll use to create a so-called permanent environment variable depends on what type of operating system and shell you’re using.

Operating System and Command Line

For macOS or Linux users, you can add environment variables to your shell configuration file. If you use zsh, add the variable to .zshrc; for bash, add it to .bashrc. For example, you could add the following line of code to the appropriate configuration file:

export API_KEY="my_key123"

Windows users can permanently set an environment variable from the command line with setx. For instance, you could run this code from your command line:

setx API_KEY "my_key123"

Keep in mind that you’ll likely need to reload your shell configuration or open a new terminal window before you’ll have access to the newly added environment variable.

Accessing Environment Variables

Once you’ve created a permanent environment variable, you’ll access it via the os module within Python similarly to how you retrieved a temporary one. For a quick check of the environment variable, print its value to the console:

import os print(os.environ["API_KEY"]) # Expected result:# my_key123

If Python cannot find a value for API_KEY, you’ll get a KeyError when you attempt to access it with os.environ. You can instead use os.getenv(), which returns None when the environment variable doesn’t exist unless you provide your own default value:

import os print(os.getenv("API_KEY"))print(os.getenv("API_VALUE"))print(os.getenv("API_VALUE", "default_value")) # Expected result:# my_key123# None# default_value

Using .env Files with python-dotenv

But what happens when you have configuration settings for a certain project that don't necessarily apply to all your programs? Python developers often separate out project-specific environment variables in a .env file. This keeps your variables separate from your Python source code without defining them across your entire system.

Here’s an example .env file:

API_KEY=my_key123DATABASE_URL=my_database_url

You would likely store this .env file in your project directory along with Python scripts that need access to it.

When it comes time to access the environment variables stored in your .env, you’ll likely want a module like python-dotenv to help load the data. You’ll need to install python-dotenv, for example, with pip:

pip install python-dotenv

Then use the load_dotenv() function to load environment variables from .env into your program’s environment and access them with os.environ or os.getenv() as usual:

from dotenv import load_dotenvimport os load_dotenv() print(os.environ["DATABASE_URL"])# Expected results:# my_database_url

Be sure to add .env to your .gitignore if you’re using Git and GitHub to track your project. Keep credentials contained within .env private and never commit them to GitHub. You may choose to create a .env.example file with the required variable names but without real sensitive data if you’d like.

Comparison Table

To better understand environment variables and when to use each approach, compare the ways to create them below. The best method depends on whether you need to persist environment variables or only use them temporarily. Here’s a quick comparison table to summarize the key similarities and differences between each technique:

No matter which method you choose, you can access individual environment variables from your code with os.environ or os.getenv().

Managing Environment Variables in Different Environments

In a professional setting, you may need to run the same application with different configuration settings for development, testing, staging, and production. For example, you may have distinct database credentials, API endpoints, or logging levels for each environment. Your program needs to take these into account, and environment variables give you an excellent way to swap in the right values without hard-coding them into your Python scripts.

Virtual Environments

You might have previously used a virtual environment to isolate a Python interpreter and necessary packages for a specific project. While the aim of both virtual environments and environment variables is to isolate some information, they aren’t the same thing. Virtual environments focus on packages, while environment variables are for configuration data.

You can work with environment variables while using an activated Python virtual environment. Access your existing permanent environment variables or set temporary ones from within it. Oftentimes, you’ll find it helpful to use a .env file alongside your virtual environment (venv) when developing programs locally.

In Production

Avoid relying on an individual user’s .env file when running production applications. Instead, use production-specific configurations supplied by the environment where your application runs. Working with a secret-management system helps further protect your production credentials.

In production, you might see configurations for hosting platforms and servers in addition to credentials like API keys. Even with a different setup, you can still access environment variables through os.environ or os.getenv(). Of course, where you store your variables depends on how you deploy your application. Cloud platforms, containers, and CI/CD pipelines each give you ways to effectively manage environment variables.

Clouds, Containers, and CI/CD

Modern deployment environments, including cloud platforms, containers, and CI/CD pipelines, have their own ways to configure environment variables. Typically, you’ll provide your variables when you deploy or run your application.

Cloud platforms allow you to rent compute or storage resources from providers like Amazon Web Services (AWS), Microsoft Azure, or Google Cloud. You may need to supply application-specific settings in cloud environments, and environment variables offer a convenient vehicle for these configurations. Cloud providers also often have managed secret stores for sensitive data like passwords and keys.

Since each container has its own environment, environment variables let you pass specific settings when starting a container on a platform like Docker. Docker, specifically, gives you two nice options that both avoid hard-coding variables into your Python code or your container image.

You can either provide a single variable when running your container:

docker run -e DATABASE_URL="my_database_url" my_image

Or you can create a .env file to supply multiple variables:

docker run --env-file .env my_image

Ultimately, environment variables work very well for containers because you can reuse the same image while changing its configuration at runtime.

CI/CD pipelines often come with separate environments for building, testing, and deploying applications, so once again, environment variables suit these systems well because you can provide different configurations and credentials to each type of environment. Some CI/CD platforms like GitHub Actions let you explicitly store your secrets away from your source code, only making them available to jobs in your pipeline, including as environment variables.

No matter which deployment environment you choose, you can continue to access environment variables from within your code using os.environ or os.getenv() from the os module. You’ll just configure them outside of your source code, following the security best practices of your platform.

Managing Secrets and Best Practices

To keep your application and secrets secure, don’t hard-code any passwords, API keys, or other credentials directly into your Python scripts. You can instead rely on environment variables to keep these configurations separate from your source code.

Never commit sensitive information to version control repositories, especially ones you plan to host publicly on platforms such as GitHub. If you choose to create a .env file to bulk-store your variables, make sure to add it to your .gitignore before pushing project files to GitHub. Doing so helps prevent you from accidentally uploading your secrets, even if you happen to run git add . to include everything.

You’ll likely want separate credentials and configurations for each environment type (development, testing, staging, and production). And try using a secrets manager for apps deployed in a production environment. Finally, remember not to put any sensitive information in your logs or error messages—who knows which user might eventually see them!

Troubleshooting Common Errors

Let’s face it, working with information stored outside of your Python script can lead to some pretty frustrating bugs. Here are a few of the most common ones you’ll encounter when setting and managing environment variables in Python along with solutions for each.

If values you’ve stored in your project’s .env file won’t load into your code, make sure that you’ve installed python-dotenv. Also double-check that you’ve called load_dotenv() from the python-dotenv library in your script. Given that you’ve done both of those things, you’ll want to verify that your .env file is in its expected location, such as your project directory. Make sure you haven’t named a permanent environment variable in your system the same thing as a variable in your .env file; load_dotenv() won’t override existing variables by default.

Speaking of permanent variables, sometimes these won’t appear because you need to launch a new terminal window or reload your shell configuration before asking Python to run your script. You could also check that you added the variable to the configuration file for the shell you’re actually using. For example, if you edit .zshrc, but run Python from bash, you won’t have access to your variable.

You’ll also want to remember that os.environ and os.getenv() return your Python environment variables as strings. This makes sense for items like API URLs or keys, but if you need a variable to specify a port number, for example, you’ll probably need to explicitly convert it to an integer. Here we’ve used os.getenv() to retrieve our port with a string default value of "5000" before converting it to an integer:

import os port = int(os.getenv("PORT", "5000"))

Wrapping Up

Environment variables are stored key-value pairs that live outside of Python code. They typically store configuration and credential information such as database URLs or API keys. You can set them temporarily from a Python script, permanently through your operating system or shell configuration, or in a .env file for all the environment variables of your Python project. Access them from your code through Python’s os module, referencing os.environ or the os.getenv() function to avoid a KeyError.

You’ll find environment variables useful when switching configurations and credentials between different environments, and you can also provide them for your cloud applications. Just be sure not to publish any sensitive information such as passwords or API keys to GitHub. You may choose to use a dedicated secrets manager for production applications.

After all that, there’s still more to fully understand environment variables in Python. Feel free to ask the AI Tutor for more information, starting from this prompt: