python-dotenv

Install the core library using pip:

pip install python-dotenv

You can load .env files directly in IPython using magic commands.

To use the default search behavior:

%load_ext dotenv
%dotenv

To specify a specific path:

%dotenv relative/or/absolute/path/to/.env

Optional flags:

• -o: Override existing variables.
• -v: Increase verbosity.

To use the command-line interface features of python-dotenv, you must install the package with the [cli] extra. If you receive an error indicating the CLI is not installed, run the following command:

pip install "python-dotenv[cli]"

Use dotenv_values() to parse a .env file into a dictionary without modifying the actual system environment variables. This is useful for advanced configuration management, such as merging multiple .env files or overriding them with os.environ manually.

from dotenv import dotenv_values

config = dotenv_values(".env")  # config = {"USER": "foo", "EMAIL": "foo@example.org"}

Both load_dotenv and dotenv_values accept a stream argument, allowing you to load variables from sources other than the filesystem, such as an in-memory buffer or a network stream.

from io import StringIO
from dotenv import load_dotenv

config = StringIO("USER=foo\nEMAIL=foo@example.org")
load_dotenv(stream=config)

Use load_dotenv() to read key-value pairs from a .env file and set them as environment variables in os.environ.

By default:

• It searches for a .env file in the current directory or higher up the directory tree.
• It does not override existing environment variables. To force an override, pass override=True.

from dotenv import load_dotenv

load_dotenv()  # reads variables from a .env file and sets them in os.environ

To prevent load_dotenv() from loading .env files or streams (useful in production or when you cannot modify third-party calls), set the following environment variable:

PYTHON_DOTENV_DISABLED=1

.env files follow a syntax similar to Bash.

Key Features:

• Variable Expansion: Supports POSIX variable expansion using the ${VAR} syntax. Bare $VAR syntax is not supported.
• Multiline Values: Single or double-quoted values can span multiple lines.
• Variable without a value: A line containing only a key (e.g., FOO) results in None when using dotenv_values(), but is ignored by load_dotenv().
• Empty values: FOO= results in an empty string.
• Comments: Values can be followed by comments.
• Quotes: Keys can be unquoted or single-quoted. Values can be unquoted, single-quoted, or double-quoted.

The dotenv CLI allows you to manipulate .env files from the terminal. To use the CLI, install the extra package:

pip install "python-dotenv[cli]"

Common Commands:

• dotenv set KEY VALUE: Set a variable.
• dotenv list: List all variables.
• dotenv list --format=json: List variables in JSON format.
• dotenv run -- python script.py: Run a command with the loaded environment variables.

$ pip install "python-dotenv[cli]"
$ dotenv set USER foo
$ dotenv set EMAIL foo@example.org
$ dotenv list
USER=foo
EMAIL=foo@example.org
$ dotenv list --format=json
{
  "USER": "foo",
  "EMAIL": "foo@example.org"
}
$ dotenv run -- python foo.py