Get, Set, and Delete Environment Variables in Python: os.environ

In Python, os.environ allows you to manage environment variables. Note that any changes only affect the current Python program. The system environment variables remain untouched.

• os.environ — Miscellaneous operating system interfaces — Python 3.11.4 documentation

The sample code in this article uses the os and subprocess modules. They are both included in the standard Python library and require no additional installation.

import os
import subprocess

os.environ

The type of os.environ is os._Environ.

print(type(os.environ))
# <class 'os._Environ'>

os._Environ is a mapping type that operates similarly to a dictionary (dict), pairing keys with their corresponding values. In this case, the keys represent the names of environment variables.

os.environ is loaded when the os module is imported. Any changes made to the system's environment variables during program execution won't affect os.environ.

The list can be displayed using print(). Outputs are omitted here.

# print(os.environ)

Just like a dictionary, you can use methods such as keys() and values(), and check the existence of keys or values with in.

• Iterate dictionary (key and value) with for loop in Python
• Check if key/value exists in dictionary in Python

Get and check environment variables

os.environ[]

The value of an environment variable can be retrieved using os.environ[name]. Specifying a nonexistent environment variable name throws a KeyError.

print(os.environ['LANG'])
# ja_JP.UTF-8

# print(os.environ['NEW_KEY'])
# KeyError: 'NEW_KEY'

os.environ.get()

The get() method of os.environ returns None or a specified default value if the environment variable is missing. It behaves similarly to a dictionary.

• Get value from dictionary by key with get() in Python

print(os.environ.get('LANG'))
# ja_JP.UTF-8

print(os.environ.get('NEW_KEY'))
# None

print(os.environ.get('NEW_KEY', 'default'))
# default

os.getenv()

The os.getenv() function is another option.

• os.getenv() — Miscellaneous operating system interfaces — Python 3.11.4 documentation

Similar to the get() method, os.getenv() returns None or a specified default value if the key is missing. If you just want to get and check the value of an environment variable, os.getenv() is useful.

print(os.getenv('LANG'))
# ja_JP.UTF-8

print(os.getenv('NEW_KEY'))
# None

print(os.getenv('NEW_KEY', 'default'))
# default

Set (add/overwrite) environment variables

Environment variables can be set by assigning a value to os.environ[name].

If you specify a new environment variable name, a new environment variable is added. If an existing environment variable name is specified, the existing value is overwritten.

os.environ['NEW_KEY'] = 'test'

print(os.environ['NEW_KEY'])
# test

os.environ['NEW_KEY'] = 'test2'

print(os.environ['NEW_KEY'])
# test2

As mentioned above, adding or overwriting environment variables only affects the current Python program. The system's environment variables remain unchanged.

Note that assigning a non-string value to an environment variable will throw a TypeError. If you wish to assign a numeric value, ensure it is specified as a string.

# os.environ['NEW_KEY'] = 100
# TypeError: str expected, not int

os.environ['NEW_KEY'] = '100'

While the os.putenv() function is available, using it to set a variable does not update os.environ. Therefore, it's better to specify the key (environment variable name) of os.environ and assign a value, as shown above.

Note: Calling putenv() directly does not change os.environ, so it’s better to modify os.environ. os.environ — Miscellaneous operating system interfaces — Python 3.11.4 documentation

Note: Potential memory leaks on certain OS

Be aware that changing values can result in memory leaks on certain operating systems.

Note: On some platforms, including FreeBSD and macOS, setting environ may cause memory leaks. Refer to the system documentation for putenv(). os.environ — Miscellaneous operating system interfaces — Python 3.11.4 documentation

This issue arises due to the specification of the operating system's putenv() function.

Successive calls to setenv() or putenv() assigning a differently sized value to the same name will result in a memory leak. The FreeBSD semantics for these functions (namely, that the contents of value are copied and that old values remain accessible indefinitely) make this bug unavoidable. Mac OS X Manual Page For putenv(3)

Delete environment variables

To delete environment variables, use the pop() method of os.environ or the del statement, which operates the same way as with a dictionary. Refer to the article below for more details.

• Remove an item from a dictionary in Python (clear, pop, popitem, del)

The pop() method returns the value of the deleted environment variable. By default, specifying a nonexistent environment variable results in a KeyError, but if a second argument is specified, it returns that value if the environment variable is not found.

os.environ['NEW_KEY'] = '100'

print(os.environ.pop('NEW_KEY'))
# 100

print(os.getenv('NEW_KEY'))
# None

# print(os.environ.pop('NEW_KEY'))
# KeyError: 'NEW_KEY'

print(os.environ.pop('NEW_KEY', None))
# None

The del statement can also be used. If the environment variable is missing, it throws a KeyError.

os.environ['NEW_KEY'] = '100'

del os.environ['NEW_KEY']

print(os.getenv('NEW_KEY'))
# None

# del os.environ['NEW_KEY']
# KeyError: 'NEW_KEY'

The os.unsetenv() function is also available, but just like os.putenv(), using it to delete an environment variable will not update os.environ. Therefore, it's preferable to delete by specifying the key (environment variable name) of os.environ as shown in the previous example.

Deletion of items in os.environ is automatically translated into a corresponding call to unsetenv(); however, calls to unsetenv() don’t update os.environ, so it is actually preferable to delete items of os.environ. os.unsetenv() — Miscellaneous operating system interfaces — Python 3.11.4 documentation

Also, note that the deletion of an environment variable only applies to the current Python program and does not affect the system's environment variables.

The effect of changing environment variables with os.environ

As mentioned repeatedly, changes to the environment variables using os.environ do not affect the system's environment variables. However, they do impact subprocesses launched within the program.

For example, the date command's output varies according to the LANG environment variable. Note that this code will not work as expected on Windows, which lacks the LANG environment variable.

The date command is called using the subprocess module.

• subprocess — Subprocess management — Python 3.11.4 documentation

The output result of date changes depending on the value of LANG.

print(os.getenv('LANG'))
# ja_JP.UTF-8

print(subprocess.check_output('date', encoding='utf-8'))
# 2023年 7月 9日 日曜日 22時47分58秒 JST
# 

os.environ['LANG'] = 'en_US'

print(subprocess.check_output('date', encoding='utf-8'))
# Sun Jul  9 22:47:58 JST 2023
# 

Note that, for explanation purposes, the LANG environment variable is changed with os.environ here, but Python has a locale module to control locales.

• locale — Internationalization services — Python 3.11.4 documentation

Switch operations based on environment variables

You can switch operations based on the value of an environment variable.

For example, you can change the output according to the LANG environment variable. Here, the startswith() method is used to determine whether the string starts with a specified string. If you want to determine an exact match, you can use ==.

• String comparison in Python (exact/partial match, etc.)

os.environ['LANG'] = 'ja_JP'

if os.getenv('LANG').startswith('ja'):
    print('こんにちは')
else:
    print('Hello')
# こんにちは

os.environ['LANG'] = 'en_US'

if os.getenv('LANG').startswith('ja'):
    print('こんにちは')
else:
    print('Hello')
# Hello