首页 Poetry logo

配置

配置 #

Poetry 可以通过 config 命令进行配置 (在此查看更多关于其用法的介绍)，或者直接在 config.toml 文件中进行配置，该文件会在您第一次运行该命令时自动创建。该文件通常位于以下目录之一

  • macOS: ~/Library/Application Support/pypoetry
  • Windows: %APPDATA%\pypoetry

对于 Unix，我们遵循 XDG 规范并支持 $XDG_CONFIG_HOME。这意味着，默认情况下为 ~/.config/pypoetry。

本地配置 #

Poetry 还提供对特定于项目的设置的支持，方法是将 --local 选项传递给 config 命令。

poetry config virtualenvs.create false --local
注意
您对 Poetry 应用程序的本地配置存储在 poetry.toml 文件中，该文件与 pyproject.toml 分开。
警告
请注意，不要将此文件签入您的仓库，因为它可能包含用户特定的或敏感信息。

列出当前配置 #

要列出当前配置，您可以使用 config 命令的 --list 选项

poetry config --list

这将为您提供类似于以下内容的结果

cache-dir = "/path/to/cache/directory"
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.options.always-copy = true
virtualenvs.options.no-pip = false
virtualenvs.options.no-setuptools = false
virtualenvs.options.system-site-packages = false
virtualenvs.path = "{cache-dir}/virtualenvs"  # /path/to/cache/directory/virtualenvs
virtualenvs.prefer-active-python = false
virtualenvs.prompt = "{project_name}-py{python_version}"

显示单个配置设置 #

如果您想查看特定设置的值，可以将它的名称传递给 config 命令

poetry config virtualenvs.path

有关支持设置的完整列表，请参阅 可用设置。

添加或更新配置设置 #

要更改或添加新的配置设置，可以在设置名称后传递一个值

poetry config virtualenvs.path /path/to/cache/directory/virtualenvs

有关支持设置的完整列表，请参阅 可用设置。

删除特定设置 #

如果您想删除先前设置的设置，可以使用 --unset 选项

poetry config virtualenvs.path --unset

然后，该设置将恢复其默认值。

使用环境变量 #

有时，特别是在使用 CI 工具与 Poetry 时，使用环境变量会更容易，而无需执行配置命令。

Poetry 支持此功能，任何设置都可以通过使用环境变量来设置。

环境变量必须以 POETRY_ 为前缀，并且由设置的名称（大写）组成，并将点和连字符替换为下划线，以下是一个示例

export POETRY_VIRTUALENVS_PATH=/path/to/virtualenvs/directory

这对于秘密设置（如凭据）也适用

export POETRY_HTTP_BASIC_MY_REPOSITORY_PASSWORD=secret

默认目录 #

Poetry 使用以下默认目录

配置目录 #

  • Linux: $XDG_CONFIG_HOME/pypoetry 或 ~/.config/pypoetry
  • Windows: %APPDATA%\pypoetry
  • MacOS: ~/Library/Application Support/pypoetry

您可以通过设置 POETRY_CONFIG_DIR 环境变量来覆盖配置目录。

数据目录 #

  • Linux: $XDG_DATA_HOME/pypoetry 或 ~/.local/share/pypoetry
  • Windows: %APPDATA%\pypoetry
  • MacOS: ~/Library/Application Support/pypoetry

您可以通过设置 POETRY_DATA_DIR 或 POETRY_HOME 环境变量来覆盖数据目录。如果设置了 POETRY_HOME，它将具有更高的优先级。

缓存目录 #

  • Linux: $XDG_CACHE_HOME/pypoetry 或 ~/.cache/pypoetry
  • Windows: %LOCALAPPDATA%\pypoetry
  • MacOS: ~/Library/Caches/pypoetry

您可以通过设置 POETRY_CACHE_DIR 环境变量来覆盖缓存目录。

可用设置 #

cache-dir #

类型: string

环境变量: POETRY_CACHE_DIR

Poetry 使用的缓存目录的路径。

默认情况下为以下目录之一

  • macOS: ~/Library/Caches/pypoetry
  • Windows: C:\Users\<username>\AppData\Local\pypoetry\Cache
  • Unix: ~/.cache/pypoetry

experimental.system-git-client #

类型: boolean

默认值: false

环境变量: POETRY_EXPERIMENTAL_SYSTEM_GIT_CLIENT

在 1.2.0 中引入

对于与 git 相关的任务，使用系统 git 客户端后端。

Poetry 默认情况下使用 dulwich 来完成与 git 相关的任务，以避免依赖于 git 客户端的可用性。

如果您遇到任何问题，请将其设置为 true 以使用系统 git 后端。

installer.max-workers #

类型: int

默认值: number_of_cores + 4

环境变量: POETRY_INSTALLER_MAX_WORKERS

在 1.2.0 中引入

在使用并行安装程序时，设置最大工作进程数。number_of_cores 由 os.cpu_count() 确定。如果这引发了 NotImplementedError 异常，则 number_of_cores 被假定为 1。

如果此配置参数设置为大于 number_of_cores + 4 的值，则最大工作进程数仍将限制在 number_of_cores + 4。

注意
当 installer.parallel 设置为 false 时，此配置将被忽略。

installer.modern-installation #

类型: boolean

默认值: true

环境变量: POETRY_INSTALLER_MODERN_INSTALLATION

在 1.4.0 中引入

使用更现代、更快的包安装方法。

如果这会导致问题，您可以通过将其设置为false来禁用它，并在问题跟踪器上报告您遇到的问题。

installer.no-binary #

类型: string | boolean

默认值: false

环境变量: POETRY_INSTALLER_NO_BINARY

在 1.2.0 中引入

设置此配置后，用户可以为所有或特定包配置包分发格式策略。

配置 描述
:all: 或 true 禁止所有包的二进制分发。
:none: 或 false 允许所有包的二进制分发。
package[,package,..] 仅禁止指定包的二进制分发。
注意
与这里描述的所有配置一样，这是一个用户特定的配置。这意味着在生成锁文件或解析依赖项时不会考虑这一点。这仅在选择应安装到 Poetry 管理的环境中的依赖项的哪个分发时应用。
注意

对于项目特定的使用，建议使用--local配置此项。

poetry config --local installer.no-binary :all:
注意

对于使用环境变量配置此项的 CI 或容器环境，这可能很有用。

export POETRY_INSTALLER_NO_BINARY=:all:
警告
除非系统范围内需要此项，否则如果在全局范围内配置，如果设置不正确，您可能会在所有项目中遇到更慢的安装时间。

installer.parallel #

类型: boolean

默认值: true

环境变量: POETRY_INSTALLER_PARALLEL

在 1.1.4 中引入

在使用新的（>=1.1.0）安装程序时使用并行执行。

solver.lazy-wheel #

类型: boolean

默认值: true

环境变量: POETRY_SOLVER_LAZY_WHEEL

在 1.8.0 中引入

不要下载整个轮子来提取元数据，而是使用HTTP 范围请求仅下载轮子的 METADATA 文件。尤其是在网络连接缓慢的情况下，此设置可以显着加快依赖项解析速度。如果缓存已经填充或服务器不支持 HTTP 范围请求，则此设置没有区别。

virtualenvs.create #

类型: boolean

默认值: true

环境变量: POETRY_VIRTUALENVS_CREATE

如果不存在，则创建一个新的虚拟环境。

如果设置为false，Poetry 不会创建新的虚拟环境。如果它检测到已启用的虚拟环境或{cache-dir}/virtualenvs或{project-dir}/.venv中存在的虚拟环境，它将向其中安装依赖项，否则它将向系统 python 环境安装依赖项。

注意
如果 Poetry 检测到它在激活的虚拟环境中运行，则无论virtualenvs.create设置的值如何，它都不会创建新的虚拟环境。
注意

请注意，将依赖项安装到系统环境可能会升级或卸载现有软件包，从而破坏其他应用程序。在安装项目后安装其他 Python 软件包可能会反过来破坏 Poetry 项目。

这就是为什么建议始终创建虚拟环境的原因。这在 Docker 容器中也是如此，因为它们也可能包含其他 Python 软件包。

virtualenvs.in-project #

类型: boolean

默认值: None

环境变量: POETRY_VIRTUALENVS_IN_PROJECT

在项目的根目录中创建虚拟环境。

如果未明确设置，poetry默认情况下将在{cache-dir}/virtualenvs下创建虚拟环境，或者如果已存在，则使用{project-dir}/.venv目录。

如果设置为true，虚拟环境将在项目根目录中名为.venv的文件夹中创建和预期。

注意

如果已经在{cache-dir}/virtualenvs下为项目创建了虚拟环境，则将此变量设置为true不会导致poetry创建或使用本地虚拟环境。

为了使此设置对已处于该状态的项目生效，您必须删除位于{cache-dir}/virtualenvs中的虚拟环境文件夹。

您可以使用命令poetry env info --path找出当前项目的虚拟环境（如果有）存储在哪里。

如果设置为false，poetry将忽略任何现有的.venv目录。

virtualenvs.options.always-copy #

类型: boolean

默认值: false

环境变量: POETRY_VIRTUALENVS_OPTIONS_ALWAYS_COPY

在 1.2.0 中引入

如果设置为true，则在创建虚拟环境时将--always-copy参数传递给virtualenv，以便将所有必需的文件复制到其中，而不是链接。

virtualenvs.options.no-pip #

类型: boolean

默认值: false

环境变量: POETRY_VIRTUALENVS_OPTIONS_NO_PIP

在 1.2.0 中引入

如果设置为true，则在创建虚拟环境时将--no-pip参数传递给virtualenv。这意味着当创建新的虚拟环境时，pip不会安装在环境中。

注意

Poetry 为了其内部操作，使用嵌入在virtualenv包中的pip轮子，该包作为 Poetry 运行时环境中的依赖项安装。如果用户在将此选项设置为true时运行poetry run pip，则使用pip的嵌入实例。

如果您希望虚拟环境中没有其他软件包，可以安全地将此选项以及no-setuptools设置为true。这对于生产环境是可取的。

virtualenvs.options.no-setuptools #

类型: boolean

默认值: false

环境变量: POETRY_VIRTUALENVS_OPTIONS_NO_SETUPTOOLS

在 1.2.0 中引入

如果设置为true，则在创建虚拟环境时将--no-setuptools参数传递给virtualenv。这意味着当创建新的虚拟环境时，setuptools不会安装在环境中。Poetry 为了其内部操作，不需要setuptools，因此可以安全地将其设置为true。

对于使用 python 3.12 或更高版本的环境，virtualenv默认情况下在创建虚拟环境时不会安装setuptools。因此，在这种环境中，此 poetry 配置选项没有效果：无论哪种方式，setuptools都不会安装。如果您的项目依赖于setuptools，则应将其声明为依赖项。

警告
一些开发工具（如 IDE）假设setuptools（和其他）软件包始终存在并可用于虚拟环境。这会导致这些工具中的某些功能无法按预期工作。

virtualenvs.options.system-site-packages #

类型: boolean

默认值: false

环境变量: POETRY_VIRTUALENVS_OPTIONS_SYSTEM_SITE_PACKAGES

让虚拟环境访问系统 site-packages 目录。适用于虚拟环境创建。

virtualenvs.path #

类型: string

默认值: {cache-dir}/virtualenvs

环境变量: POETRY_VIRTUALENVS_PATH

创建虚拟环境的目录。

注意
此设置控制全局虚拟环境存储路径。它很可能在本地级别没有用。要将虚拟环境存储在项目根目录中，请参见virtualenvs.in-project。

virtualenvs.prefer-active-python（实验性） #

类型: boolean

默认值: false

环境变量: POETRY_VIRTUALENVS_PREFER_ACTIVE_PYTHON

在 1.2.0 中引入

使用当前激活的 Python 版本创建新的虚拟环境。如果设置为false，则使用 Poetry 安装期间使用的 Python 版本。

virtualenvs.prompt #

类型: string

默认值: {project_name}-py{python_version}

环境变量: POETRY_VIRTUALENVS_PROMPT

在 1.2.0 中引入

定义激活虚拟环境时显示的提示的格式字符串。变量project_name和python_version可用于格式化。

repositories.<name>.url #

类型: string

环境变量: POETRY_REPOSITORIES_<NAME>_URL

设置<name>的存储库 URL。

有关更多信息，请参见可发布的存储库。

http-basic.<name>.[username|password]: #

类型: string

环境变量: POETRY_HTTP_BASIC_<NAME>_USERNAME, POETRY_HTTP_BASIC_<NAME>_PASSWORD

设置<name>的存储库凭据（username和password）。有关更多信息，请参见存储库 - 配置凭据。

pypi-token.<name>: #

类型: string

环境变量: POETRY_PYPI_TOKEN_<NAME>

设置<name>的存储库凭据（使用 API 令牌）。有关更多信息，请参见存储库 - 配置凭据。

certificates.<name>.cert: #

类型: string | boolean

环境变量: POETRY_CERTIFICATES_<NAME>_CERT

为存储库<name>设置自定义证书颁发机构。有关更多信息，请参见存储库 - 配置凭据 - 自定义证书颁发机构。

如果应跳过此存储库的 TLS 证书验证，则可以将此配置设置为false。

certificates.<name>.client-cert: #

类型: string

环境变量: POETRY_CERTIFICATES_<NAME>_CLIENT_CERT

为存储库<name>设置客户端证书。有关更多信息，请参见存储库 - 配置凭据 - 自定义证书颁发机构。

keyring.enabled: #

类型: boolean

默认值: true

环境变量: POETRY_KEYRING_ENABLED

启用系统密钥环以存储凭据。有关更多信息，请参见存储库 - 配置凭据。