python-dotenv

python-dotenv从.env文件中读取键值对并将其设置为环境变量。它有助于按照12因素原则开发应用程序。

• 入门
• 其他用例
  • 在不更改环境的情况下加载配置
  • 将配置解析为流
  • 在IPython中加载.env文件
• 命令行界面
• 文件格式
  • 多行值
  • 变量扩展
• 相关项目
• 致谢

入门

pip install python-dotenv

如果您的应用程序从环境变量获取配置，比如12因子应用，那么在开发环境中启动它并不太实用，因为您必须自己设置这些环境变量。

为了帮助您，您可以在应用程序中添加Python-dotenv，使其在存在时（例如在开发中）从.env文件加载配置，同时仍然可以通过环境进行配置。

from dotenv import load_dotenv

load_dotenv()  # take environment variables from .env.

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

默认情况下，load_dotenv不会覆盖现有的环境变量。

要配置开发环境，请将.env添加到您项目根目录下

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

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

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

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

您可能希望将.env添加到.gitignore中，特别是如果它包含密码等机密信息。

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

其他用例

在不更改环境的情况下加载配置

dotenv_values函数大致与load_dotenv相同，但它不会影响环境，只是返回一个包含从.env文件中解析出的值的dict。

from dotenv import dotenv_values

config = dotenv_values(".env")  # config = {"USER": "foo", "EMAIL": "[email protected]"}

这显著提高了配置管理能力

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
}

将配置解析为流

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

from io import StringIO

from dotenv import load_dotenv

config = StringIO("USER=foo\n[email protected]")
load_dotenv(stream=config)

在IPython中加载.env文件

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

%load_ext dotenv
%dotenv

您也可以指定路径

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

可选标志

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

命令行界面

CLI界面dotenv也已包含，它可以帮助您在不手动打开的情况下操作.env文件。

$ pip install "python-dotenv[cli]"
$ dotenv set USER foo
$ dotenv set EMAIL [email protected]
$ dotenv list
USER=foo
EMAIL=[email protected]
$ dotenv list --format=json
{
  "USER": "foo",
  "EMAIL": "[email protected]"
}
$ 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文件中的值。
• 如果提供，则默认值。
• 空字符串。

相关项目

• Honcho - 用于管理基于Procfile的应用程序。
• django-dotenv
• django-environ
• django-environ-2
• django-configuration
• dump-env
• environs
• dynaconf
• parse_it
• python-decouple

致谢

本项目由Saurabh Kumar和Bertrand Bonnefoy-Claudet维护，并且没有这些出色的人的支持是难以实现的。

变更日志

本项目所有显著的变更都将记录在此文件中。

格式基于Keep a Changelog，本项目遵循语义化版本控制。

1.0.1 - 2024-01-23

修复

• 优雅地处理从zip文件导入的代码（由@samwyma在#456中提出）
• 允许使用load_dotenv的模块在单独的线程中启动时被重新加载（由@freddyaboulton在#497中提出）
• 修复删除后未关闭文件的问题，处理重写函数中的错误（由@Qwerty-133在#469中提出）

杂项

• 在测试中使用pathlib.Path（由@eumiro在#466中提出）
• 修复changelog.md中发布日期的年份（由@jankislinger在#454中提出）
• 在README链接中使用https（由@Nicals在#474中提出）

1.0.0 - 2023-02-24

修复

• 停止支持python 3.7，添加python 3.12-dev（由@theskumar在#449中提出）
• 处理当前工作目录不存在的情形（由@jctanner在#446中提出）

0.21.1 - 2023-01-21

新增

• 在CI中使用Python 3.11非beta版（由@bbc2在#438中提出）
• 使变量代码现代化（由@Nougat-Waffle在#434中提出）
• 使main.py和parser.py代码现代化（由@Nougat-Waffle在#435中提出）
• 改进cli.py和init.py的简洁性（由@Nougat-Waffle在#439中提出）
• 当env文件无法打开时，改进get和list命令的错误信息（由@bbc2在#441中提出）
• 更新许可协议以符合BSD OSI模板（由@lsmith77在#433中提出）

修复

• 修复当"dest"变量未定义时的越界错误（由@theGOTOguy在#413中提出）
• 修复IPython测试中关于过时magic的警告（由@bbc2在#440中提出）
• 修复dotenv_path变量的类型提示，添加StrPath别名（由@eaf在#432中提出）

0.21.0 - 2022-09-03

新增

• CLI：添加通过'python -m'调用的支持。（由@theskumar在#395中提出）
• load_dotenv函数现在返回False。（由@larsks在#388中提出）
• CLI：为列表命令添加--format=选项。（由@sammck在#407中提出）

修复

• 停止支持Python 3.5和3.6，并升级GA（由@eggplants在#393中提出）
• 使用open而不是io.open。（由@rabinadk1在#389中提出）
• 改进无值的变量的文档（由@bbc2在#390中提出）
• 将parse_it添加到相关项目（由@naorlivne在#410中提出）
• 更新README.md（由@harveer07在#415中提出）
• 使用MkDocs直接使用改进文档（由@bbc2在#398中提出）

0.20.0 - 2022-03-24

新增

• 向 get_key、set_key 和 unset_key 函数添加 encoding（《Optional[str]》）参数。（由 @bbc2 提出，编号 #379）

修复

• 使用字典来指定 setuptools.setup 的 entry_points 参数。（由 @mgorny 提出，编号 #376）
• 不要构建通用的轮子。（由 @bbc2 提出，编号 #387）

0.19.2 - 2021-11-11

修复

• 在 set_key 中，如果需要，在新的条目之前添加缺失的换行符。（由 @bbc2 提出，编号 #361）

0.19.1 - 2021-08-09

新增

• 添加对 Python 3.10 的支持。（由 @theskumar 提出，编号 #359）

0.19.0 - 2021-07-24

更改

• 需要 Python 3.5 或更高版本。不再支持 Python 2 和 3.4。（由 @bbc2 提出，编号 #341）

新增

• set_key 和 unset_key 的 dotenv_path 参数现在类型为 Union[str, os.PathLike]，而不是仅为 os.PathLike。（由 @bbc2 提出，编号 #347）
• load_dotenv 和 dotenv_values 的 stream 参数现在可以是文本流（《IO[str]》），包括如 io.StringIO("foo") 和 open("file.env", "r") 的值。（由 @bbc2 提出，编号 #348）

0.18.0 - 2021-06-20

更改

• 如果 quote_mode 不是 always、auto 或 never 之一，则在 set_key 中引发 ValueError。（由 @bbc2 提出，编号 #330）
• 使用 set_key 或 dotenv set <key> <value> 将值写入 .env 文件时（由 @bbc2 提出，编号 #330）
  • 使用单引号而不是双引号。
  • 不要删除周围的引号。
  • 在 auto 模式下，如果值只包含字母数字字符（通过 string.isalnum 确定），则不要添加引号。

0.17.1 - 2021-04-29

修复

• 修复依赖于 PYTHONPATH 的构建环境的测试（由 @befeleme 提出，编号 #318）。

0.17.0 - 2021-04-02

更改

• 使 dotenv get <key> 只显示值，不显示 key=value。（由 @bbc2 提出，编号 #313）

新增

• 向 dotenv run 添加 --override/--no-override 选项（由 @zueve 和 @bbc2 提出，编号 #312）。

0.16.0 - 2021-03-27

更改

• load_dotenv 和 dotenv_values 的 encoding 参数的默认值现在为 "utf-8" 而不是 None。（由 @bbc2 提出，编号 #306）
• 修复在变量展开中，当 override=False 时，解析顺序的问题。（由 @bbc2 提出，编号 #287）

0.15.0 - 2020-10-28

新增

• 将 --export 选项添加到 set，以便它将 export 预先绑定（由 @jadutter 提出，编号 #270）。

更改

• 如果当前目录中没有找到 .env 文件，则使 set 命令在当前目录中创建 .env 文件（由 @jadutter 提出，编号 #270）。

修复

• 修复重复键的潜在空展开值（由 @bbc2 提出，编号 #260）。
• 修复 Python 3.5.0 和 3.5.1 上的导入错误（由 @gongqingkui 提出，编号 #267）。
• 修复解析包含多个相邻空格或制表符字符的未引号值的错误（由 @bbc2 提出，编号 #277，由 @x-yuri 审查）。

0.14.0 - 2020-07-03

更改

• 在变量展开中，文件中的权限定义高于环境中的权限（由 @elbehery95 提出，编号 #256）。

修复

• 改进找不到文件时的错误消息（由 @snobu 提出，编号 #245）。
• 在包元数据中使用 HTTPS URL（由 @ekohl 提出，编号 #251）。

0.13.0 - 2020-04-16

新增

• 在变量展开中添加类似 Bash 的默认值支持（由 @bbc2 提出，编号 #248）。

0.12.0 - 2020-02-28

更改

• 当由 PyInstaller 打包时，使用当前工作目录来查找 .env（由 @gergelyk 提出，编号 #213）。

修复

• 修复由 set_key 编写的转义引号值的错误 (#236 由 @bbc2 提交)。
• 修复在环境变量没有值时 dotenv run 冲突 (#237 由 @yannham 提交)。
• 删除最后一行空时出现的警告 (#238 由 @bbc2 提交)。

0.11.0 - 2020-02-07

新增

• 向 load_dotenv 和 dotenv_values 添加 interpolate 参数以禁用插值 (#232 由 @ulyssessouza 提交)。

更改

• 使用日志代替警告 (#231 由 @bbc2 提交)。

修复

• 修复非 UTF-8 环境中的安装 (#225 由 @altendky 提交)。
• 修复 PyPI 分类器 (#228 由 @bbc2 提交)。

0.10.5 - 2020-01-19

修复

• 修复处理格式不正确的行和没有值的行 (#222 由 @bbc2 提交)
  • 当键没有值时不打印警告。
  • 拒绝更多格式不正确的行（例如 "A: B", "a='b',c")。
• 修复处理只包含注释的行的错误 (#224 由 @bbc2 提交)。

0.10.4 - 2020-01-17

新增

• 使输入类型可选 (#179 由 @techalchemy 提交)。
• 在格式不正确的行上打印警告 (#211 由 @bbc2 提交)。
• 支持没有值的键 (#220 由 @ulyssessouza 提交)。

0.10.3

• 改进交互模式检测 (@andrewsmith)(#183)。
• 重构解析器以修复解析不一致 (#170 由 @bbc2)(#170)。
  • 仅在双引号字符串中将转义字符解释为控制字符。
  • 只有当其前有空格时，才将 # 解释为注释的开始。

0.10.2

• 添加类型提示并将其暴露给用户 (@qnighy)(#172)
• load_dotenv 和 dotenv_values 现在接受一个 encoding 参数，默认为 None (@theskumar)(@earlbread)([#161])
• 修复 Python 2 中 str/unicode 不一致性：现在值总是 str。 (@bbc2)(#121)
• 修复 Python 2 中 0.10.0 版本引入的 Unicode 错误 (@bbc2)(#176)

0.10.1

• 修复没有值的变量的解析 (#158 由 @asyncee)(@bbc2)(#158)

0.10.0

• 在未引用的值中添加对 UTF-8 的支持 (#148 由 @bbc2)(#148)
• 添加对尾随注释的支持 (#148 由 @bbc2)(#148)
• 在值中添加对反斜杠的支持 (#148 由 @bbc2)(#148)
• 在值中添加对换行符的支持 (#148 由 @bbc2)(#148)
• 在 Windows 上使用 Python2 时强制环境变量转换为 str (@greyli)
• 删除对 Python 3.3 的支持 (@greyli)
• 修复 stderr/-out/-in 重定向 (@venthur)

0.9.0

• 向 cli 添加 --version 参数 (@venthur)
• 启用从当前目录加载 (@cjauvin)
• 添加 'dotenv run' 命令以调用具有 .env 的任意 shell 脚本 (@venthur)

0.8.1

• 为文档添加测试 (@Flimm)
• 使 'cli' 支持可选。使用 pip install python-dotenv[cli]。 (@theskumar)

0.8.0

• set_key 和 unset_key 仅修改受影响的文件而不是解析和重新写入文件，这导致注释和其他文件内容保持不变。
• 支持在行中添加 export 前缀。
• 内部重构 (@theskumar)
• 允许 load_dotenv 和 dotenv_values 与 StringIO() 一起使用 (@alanjds)(@theskumar)(#78)

0.7.1

• 移除对 iPython 的硬依赖 (@theskumar)

0.7.0

• 支持通过 .env 覆盖系统环境变量。 (@milonimrod) (#63)
• 默认禁用 ".env 未找到" 警告 (@maxkoryukov) (#57)

0.6.5

• 支持特殊字符 \。 (@pjona) (#60)

0.6.4

• 修复单引号问题 (@Flimm) (#52)

0.6.3

• 在 setup.py 中处理 Unicode 异常 (#46)

0.6.2

• 修复 dotenv 列表命令 (@ticosax)
• 添加 iPython 支持 (@tillahoffmann)

0.6.0

• 放弃对 Python 2.6 的支持
• 处理引号值中的转义字符和新行。 (感谢 @iameugenejo)
• 移除无引号键/值周围的任何空格。 (感谢 @paulochf)
• 添加 POSIX 变量扩展。 (感谢 @hugochinchilla)

0.5.1

• 修复 find_dotenv - 现在从调用此函数的文件开始搜索。

0.5.0

• 添加 find_dotenv 方法，尝试找到 .env 文件。 (感谢 @isms)

0.4.0

• cli: 添加 -q/--quote 选项以控制 .env 中值的引号行为。 (感谢 @hugochinchilla)。
• 提高测试覆盖率。