gituser/docker_multiarch/: python-dotenv-1.1.0 metadata and description

Homepage Simple index

Read key-value pairs from a .env file and set them as environment variables

author Saurabh Kumar
author_email me+github@saurabh-kumar.com
classifiers
  • Development Status :: 5 - Production/Stable
  • Programming Language :: Python
  • Programming Language :: Python :: 3
  • Programming Language :: Python :: 3.9
  • Programming Language :: Python :: 3.10
  • Programming Language :: Python :: 3.11
  • Programming Language :: Python :: 3.12
  • Programming Language :: Python :: 3.13
  • Programming Language :: Python :: Implementation :: PyPy
  • Intended Audience :: Developers
  • Intended Audience :: System Administrators
  • License :: OSI Approved :: BSD License
  • Operating System :: OS Independent
  • Topic :: System :: Systems Administration
  • Topic :: Utilities
  • Environment :: Web Environment
description_content_type text/markdown
keywords environment variables,deployments,settings,env,dotenv,configurations,python
license BSD-3-Clause
provides_extras cli
requires_dist
  • click>=5.0; extra == "cli"
requires_python >=3.9
File Tox results History
python_dotenv-1.1.0-py3-none-any.whl
Size
20 KB
Type
Python Wheel
Python
3

python-dotenv

Build Status PyPI version

python-dotenv reads key-value pairs from a .env file and can set them as environment variables. It helps in the development of applications following the 12-factor principles.

Getting Started

pip install python-dotenv

If your application takes its configuration from environment variables, like a 12-factor application, launching it in development is not very practical because you have to set those environment variables yourself.

To help you with that, you can add python-dotenv to your application to make it load the configuration from a .env file when it is present (e.g. in development) while remaining configurable via the environment:

from dotenv import load_dotenv

load_dotenv()  # take environment variables

# Code of your application, which uses environment variables (e.g. from `os.environ` or
# `os.getenv`) as if they came from the actual environment.

By default, load_dotenv doesn't override existing environment variables and looks for a .env file in same directory as python script or searches for it incrementally higher up.

To configure the development environment, add a .env in the root directory of your project:

.
├── .env
└── foo.py

The syntax of .env files supported by python-dotenv is similar to that of Bash:

# Development settings
DOMAIN=example.org
ADMIN_EMAIL=admin@${DOMAIN}
ROOT_URL=${DOMAIN}/app

If you use variables in values, ensure they are surrounded with { and }, like ${DOMAIN}, as bare variables such as $DOMAIN are not expanded.

You will probably want to add .env to your .gitignore, especially if it contains secrets like a password.

See the section "File format" below for more information about what you can write in a .env file.

Other Use Cases

Load configuration without altering the environment

The function dotenv_values works more or less the same way as load_dotenv, except it doesn't touch the environment, it just returns a dict with the values parsed from the .env file.

from dotenv import dotenv_values

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

This notably enables advanced configuration management:

import os
from dotenv import dotenv_values

config = {
    **dotenv_values(".env.shared"),  # load shared development variables
    **dotenv_values(".env.secret"),  # load sensitive variables
    **os.environ,  # override loaded values with environment variables
}

Parse configuration as a stream

load_dotenv and dotenv_values accept streams via their stream argument. It is thus possible to load the variables from sources other than the filesystem (e.g. the network).

from io import StringIO

from dotenv import load_dotenv

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

Load .env files in IPython

You can use dotenv in IPython. By default, it will use find_dotenv to search for a .env file:

%load_ext dotenv
%dotenv

You can also specify a path:

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

Optional flags:

Command-line Interface

A CLI interface dotenv is also included, which helps you manipulate the .env file without manually opening it.

$ 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

Run dotenv --help for more information about the options and subcommands.

File format

The format is not formally specified and still improves over time. That being said, .env files should mostly look like Bash files.

Keys can be unquoted or single-quoted. Values can be unquoted, single- or double-quoted. Spaces before and after keys, equal signs, and values are ignored. Values can be followed by a comment. Lines can start with the export directive, which does not affect their interpretation.

Allowed escape sequences:

Multiline values

It is possible for single- or double-quoted values to span multiple lines. The following examples are equivalent:

FOO="first line
second line"

FOO="first line\nsecond line"

Variable without a value

A variable can have no value:

FOO

It results in dotenv_values associating that variable name with the value None (e.g. {"FOO": None}. load_dotenv, on the other hand, simply ignores such variables.

This shouldn't be confused with FOO=, in which case the variable is associated with the empty string.

Variable expansion

python-dotenv can interpolate variables using POSIX variable expansion.

With load_dotenv(override=True) or dotenv_values(), the value of a variable is the first of the values defined in the following list:

With load_dotenv(override=False), the value of a variable is the first of the values defined in the following list:

Related Projects

Acknowledgements

This project is currently maintained by Saurabh Kumar and Bertrand Bonnefoy-Claudet and would not have been possible without the support of these awesome people.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unrelased]

Feature

Fixed

Misc

1.0.1 - 2024-01-23

Fixed

Misc

1.0.0 - 2023-02-24

Fixed

0.21.1 - 2023-01-21

Added

Fixed

0.21.0 - 2022-09-03

Added

Fixed

0.20.0 - 2022-03-24

Added

Fixed

0.19.2 - 2021-11-11

Fixed

0.19.1 - 2021-08-09

Added

0.19.0 - 2021-07-24

Changed

Added

0.18.0 - 2021-06-20

Changed

0.17.1 - 2021-04-29

Fixed

0.17.0 - 2021-04-02

Changed

Added

0.16.0 - 2021-03-27

Changed

0.15.0 - 2020-10-28

Added

Changed

Fixed

0.14.0 - 2020-07-03

Changed

Fixed

0.13.0 - 2020-04-16

Added

0.12.0 - 2020-02-28

Changed

Fixed

0.11.0 - 2020-02-07

Added

Changed

Fixed

0.10.5 - 2020-01-19

Fixed

0.10.4 - 2020-01-17

Added

0.10.3

0.10.2

0.10.1

0.10.0

0.9.0

0.8.1

0.8.0

0.7.1

0.7.0

0.6.5

0.6.4

0.6.3

0.6.2

0.6.0

0.5.1

0.5.0

0.4.0