python-dotenv

python-dotenv 从 .env 文件读取键值对，并将它们设置为环境变量。它有助于遵循 12-factor 原则的应用程序的开发。

入门
其他用例
命令行界面
文件格式
- 多行值
- 变量扩展
相关项目
致谢

入门

pip install python-dotenv

如果您的应用程序从环境变量获取配置（例如，遵循 12-factor 应用程序），那么在开发环境中启动它并不十分实用，因为您必须自己设置这些环境变量。

为了帮助您解决这个问题，您可以将 python-dotenv 添加到您的应用程序中，使其在存在 .env 文件时（例如在开发环境中）加载配置，同时仍然可以通过环境变量进行配置：

from dotenv import load_dotenv

load_dotenv()  # 从 .env 文件读取变量并将其设置到 os.environ

# 您的应用程序代码，它使用环境变量（例如来自 `os.environ` 或
# `os.getenv`）好像它们来自实际的环境。

默认情况下，load_dotenv() 将：

在 Python 脚本所在的目录（或其父目录）中查找 .env 文件。
读取每个键值对并将其添加到 os.environ。
不覆盖 已设置的环境变量，除非您明确传递 override=True。

要配置开发环境，请在您的项目根目录中添加一个 .env 文件：

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

python-dotenv 支持的 .env 文件语法与 Bash 类似：

# 开发设置
DOMAIN=example.org
ADMIN_EMAIL=admin@${DOMAIN}
ROOT_URL=${DOMAIN}/app

如果您在值中使用变量，请确保它们被 { 和 } 包围，例如 ${DOMAIN}，因为裸变量（如 $DOMAIN）不会被展开。

您可能希望将 .env 添加到您的 .gitignore 中，特别是当它包含密码等敏感信息时。

有关可以在 .env 文件中写入的内容的更多信息，请参阅下面的“文件格式”部分。

其他用例

加载配置而不更改环境变量

函数 dotenv_values 的工作方式与 load_dotenv 大致相同，只是它不会触碰环境变量，它只返回一个 dict，其中包含从 .env 文件解析的值。

from dotenv import dotenv_values

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

这特别支持高级配置管理：

import os
from dotenv import dotenv_values

config = {
    **dotenv_values(".env.shared"),  # 加载共享开发变量
    **dotenv_values(".env.secret"),  # 加载敏感变量
    **os.environ,  # 用环境变量覆盖加载的值
}

将配置解析为流

load_dotenv 和 dotenv_values 通过它们的 stream 参数接受流。因此，可以从文件系统以外的源（例如网络）加载变量。

from io import StringIO

from dotenv import load_dotenv

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

在 IPython 中加载 .env 文件

您可以在 IPython 中使用 dotenv。默认情况下，它将使用 find_dotenv 搜索 .env 文件：

%load_ext dotenv
%dotenv

您也可以指定一个路径：

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

可选标志：

使用 -o 覆盖现有变量。
使用 -v 增加详细程度。

禁用 load_dotenv

设置 PYTHON_DOTENV_DISABLED=1 可以禁用 load_dotenv() 加载 .env 文件或流。当您无法修改第三方包的调用或在生产环境中使用时，这很有用。

命令行界面

还包含一个名为 dotenv 的 CLI 接口，它可以帮助您在不手动打开的情况下操作 .env 文件。

$ 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

有关选项和子命令的更多信息，请运行 dotenv --help。

文件格式

该格式没有正式规定，并且仍在不断改进。也就是说，.env 文件在大多数情况下应类似于 Bash 文件。

键可以是未加引号或单引号引起来的。值可以是未加引号、单引号或双引号引起来的。键、等号和值之前的空格将被忽略。值后面可以跟注释。行可以以 export 指令开头，这不会影响它们的解释。

允许的转义序列：

在单引号值中：\\, \'
在双引号值中：\\, \', \", \a, \b, \f, \n, \r, \t, \v

多行值

单引号或双引号值可以跨越多行。以下示例是等效的：

FOO="first line
second line"

FOO="first line\nsecond line"

没有值的变量

变量可以没有值：

FOO

这会导致 dotenv_values 将该变量名与值 None 关联（例如 {"FOO": None}）。另一方面，load_dotenv 则会简单地忽略此类变量。

这不应与 FOO= 混淆，在这种情况下，变量与空字符串关联。

变量扩展

python-dotenv 可以使用 POSIX 变量扩展来内插变量。

使用 load_dotenv(override=True) 或 dotenv_values() 时，变量的值是以下列表中定义的该变量值的第一个：

该变量在 .env 文件中的值。
该变量在环境变量中的值。
默认值（如果提供）。
空字符串。

使用 load_dotenv(override=False) 时，变量的值是以下列表中定义的该变量值的第一个：

该变量在环境变量中的值。
该变量在 .env 文件中的值。
默认值（如果提供）。
空字符串。

致谢

该项目目前由 Saurabh Kumar 和 Bertrand Bonnefoy-Claudet 维护，并且离不开这些杰出人士的支持。