Repository files navigation

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

• Getting Started
• Other Use Cases
  • Load configuration without altering the environment
  • Parse configuration as a stream
  • Load .env files in IPython
• Command-line Interface
• File format
  • Multiline values
  • Variable expansion
• Related Projects
• Acknowledgements

pip install python-dotenv

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

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

fromdotenvimportload_dotenvload_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 yourproject:

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

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

# Development settingsDOMAIN=example.orgADMIN_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 containssecrets like a password.

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

The functiondotenv_values works more or less the same way asload_dotenv, except itdoesn't touch the environment, it just returns adict with the values parsed from the.env file.

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

This notably enables advanced configuration management:

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

load_dotenv anddotenv_values acceptstreams via theirstreamargument. It is thus possible to load the variables from sources other than thefilesystem (e.g. the network).

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

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

%load_extdotenv%dotenv

You can also specify a path:

%dotenvrelative/or/absolute/path/to/.env

Optional flags:

• -o to override existing variables.
• -v for increased verbosity.

SetPYTHON_DOTENV_DISABLED=1 to disableload_dotenv() from loading .env files or streams. Useful when you can't modify third-party package calls or in production.

A CLI interfacedotenv is also included, which helps you manipulate the.env filewithout manually opening it.

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

Rundotenv --help for more information about the options and subcommands.

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 followedby a comment. Lines can start with theexport directive, which does not affect theirinterpretation.

Allowed escape sequences:

• in single-quoted values:\\,\'
• in double-quoted values:\\,\',\",\a,\b,\f,\n,\r,\t,\v

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

FOO="first linesecond line"

FOO="first line\nsecond line"

A variable can have no value:

FOO

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

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

python-dotenv can interpolate variables using POSIX variable expansion.

Withload_dotenv(override=True) ordotenv_values(), the value of a variable is thefirst of the values defined in the following list:

• Value of that variable in the.env file.
• Value of that variable in the environment.
• Default value, if provided.
• Empty string.

Withload_dotenv(override=False), the value of a variable is the first of the valuesdefined in the following list:

• Value of that variable in the environment.
• Value of that variable in the.env file.
• Default value, if provided.
• Empty string.

• Honcho - For managingProcfile-based applications.
• django-dotenv
• django-environ
• django-environ-2
• django-configuration
• dump-env
• environs
• dynaconf
• parse_it
• python-decouple

This project is currently maintained bySaurabh Kumar andBertrand Bonnefoy-Claudet and would not have been possiblewithout the support of theseawesomepeople.