配置项目

PDM 的 config 命令的工作方式与 git config 相似，只是不需要 --list 来显示配置。

显示当前配置：

  1. pdm config

获取单个配置：

  1. pdm config pypi.url

更改配置值并存储在家庭配置中：

  1. pdm config pypi.url "https://test.pypi.org/simple"

默认情况下，配置会全局更改，如果你想让配置只被此项目看到，添加一个 --local 标志：

  1. pdm config --local pypi.url "https://test.pypi.org/simple"

任何本地配置将存储在项目根目录下的 pdm.toml 中。

配置文件

配置文件按以下顺序搜索：

  1. <PROJECT_ROOT>/pdm.toml - 项目配置
  2. <CONFIG_ROOT>/config.toml - 家庭配置
  3. <SITE_CONFIG_ROOT>/config.toml - 站点配置

其中 <CONFIG_ROOT> 是：

而 <SITE_CONFIG_ROOT> 是：

如果使用了 -g/--global 选项，第一项将被替换为 <CONFIG_ROOT>/global-project/pdm.toml。

你可以在 Configuration Page 中找到所有可用的配置项。

配置 Python 查找器

默认情况下，PDM 会尝试在以下来源中查找 Python 解释器：

  • venv: PDM virtualenv 位置
  • path: PATH 环境变量
  • pyenv: pyenv 安装根
  • rye: rye 工具链安装根
  • asdf: asdf python 安装根
  • winreg: Windows 注册表

你可以通过设置 python.providers 配置键来取消选择其中一些或更改顺序：

  1. pdm config python.providers rye   # 仅 Rye 来源
  2. pdm config python.providers pyenv,asdf  # pyenv 和 asdf

允许预发布版本出现在解析结果中

默认情况下，pdm 的依赖关系解析器会忽略预发布版本，除非对于给定依赖项的版本范围没有稳定的版本。这种行为可以通过在 [tool.pdm.resolution] 表中将 allow-prereleases 设置为 true 来更改：

  1. [tool.pdm.resolution]
  2. allow-prereleases = true

配置包索引

你可以通过在 pyproject.toml 中指定源或通过 pypi.* 配置来告诉 PDM 在哪里找到包。

在 pyproject.toml 中添加源：

  1. [[tool.pdm.source]]
  2. name = "private"
  3. url = "https://private.pypi.org/simple" 
  4. verify_ssl = true

通过 pdm config 更改默认索引：

  1. pdm config pypi.url "https://test.pypi.org/simple"

通过 pdm config 添加额外的索引：

  1. pdm config pypi.extra.url "https://extra.pypi.org/simple"

可用的配置选项有：

  • url: 索引的 URL
  • verify_ssl: (可选)是否验证 SSL 证书，默认为 true
  • username: (可选)索引的用户名
  • password: (可选)索引的密码
  • type: (可选)索引或 find_links，默认为索引

??? 注意 “关于源类型” 默认情况下，所有源都是 PEP 503 风格的 “索引”，像 pip 的 --index-url 和 --extra-index-url，然而，你可以将类型设置为 find_links，其中包含要直接查找的文件或链接。查看 这个答案 了解两种类型之间的区别。

这些配置按以下顺序读取，以构建最终的源列表：

  • 如果 pyproject.toml 中的任何源的 name 字段中没有出现 pypi，则为 pypi.url
  • pyproject.toml 中的源
  • PDM 配置中的 pypi.<name>.url。

你可以将 pypi.ignore_stored_index 设置为 true，以禁用所有来自 PDM 配置的索引，并仅使用 pyproject.toml 中指定的那些。

!!! TIP “禁用默认的 PyPI 索引” 如果你想省略默认的 PyPI 索引，只需将源名称设置为 pypi，该源将 替换 它。

  1. ```toml
  2. [[tool.pdm.source]]
  3. url = "https://private.pypi.org/simple" 
  4. verify_ssl = true
  5. name = "pypi"
  6. ```

??? 注意 “在 pyproject.toml 或配置中的索引” 当你想与将要使用项目的其他人共享索引时，应该在 pyproject.toml 中添加它们。 例如，一些包只存在于私有索引中，如果有人没有配置索引，则无法安装。 否则，将它们存储在本地配置中，其他人不会看到。

尊重源的顺序

默认情况下，所有源都被视为平等的，来自它们的包会按版本和 wheel 标签排序，选择最匹配的最高版本。

在某些情况下，您可能希望从首选源返回包，并在前者缺少时从其他源搜索。PDM 支持通过读取配置 respect-source-order 来实现这一点：

  1. [tool.pdm.resolution]
  2. respect-source-order = true

为个别包指定索引

你可以使用 tool.pdm.source 表下的 include_packages 和 exclude_packages 配置来将包绑定到特定的源。

  1. [[tool.pdm.source]]
  2. name = "private"
  3. url = "https://private.pypi.org/simple" 
  4. include_packages = ["foo", "foo-*"]
  5. exclude_packages = ["bar-*"]

通过上述配置，任何匹配 foo 或 foo-* 的包将只从 private 索引中搜索，任何匹配 bar-* 的包将从除 private 之外的所有索引中搜索。

include_packages 和 exclude_packages 都是可选的，并接受 glob 模式列表，当模式匹配时，include_packages 会独占生效。

在索引中存储凭据

你可以通过 ${ENV_VAR} 变量扩展在 URL 中指定凭据，这些变量将从环境变量中读取：

  1. [[tool.pdm.source]]
  2. name = "private"
  3. url = "https://${PRIVATE_PYPI_USERNAME}:${PRIVATE_PYPI_PASSWORD}@private.pypi.org/simple"

配置 HTTPS 证书

你可以为 HTTPS 请求使用自定义的 CA 捆绑包或客户端证书。它可以分别为索引（用于包下载）和存储库（用于上传）进行配置：

  1. pdm config pypi.ca_certs /path/to/ca_bundle.pem
  2. pdm config repository.pypi.ca_certs /path/to/ca_bundle.pem

此外，可以使用系统信任库，而不是捆绑的 certifi 证书来验证 HTTPS 证书。这种方法通常可以在没有额外配置的情况下支持企业代理证书。

要使用 truststore，你需要 Python 3.10 或更高版本，并在与 PDM 相同的环境中安装 truststore：

  1. pdm self add truststore

索引配置合并

索引配置与 [[tool.pdm.source]] 表的 name 字段或配置文件中的 pypi.<name> 键合并。 这使你可以分别存储 URL 和凭据，以避免在源代码控制中暴露秘密。 例如，如果你有以下配置：

  1. [[tool.pdm.source]]
  2. name = "private"
  3. url = "https://private.pypi.org/simple"

你可以在配置文件中存储凭据：

  1. pdm config pypi.private.username "foo"
  2. pdm config pypi.private.password "bar"

PDM 可以从两个地方检索 private 索引的配置。

如果索引需要用户名和密码，但它们无法从环境变量或配置文件中找到，PDM 将提示你输入它们。或者，如果安装了 keyring，它将被用作凭据存储。PDM 可以使用来自安装包或 CLI 的 keyring。

中央安装缓存

如果一个包被系统上的许多项目所需要，每个项目都必须保留自己的副本。这可能是对磁盘空间的浪费，特别是对于数据科学和机器学习项目。

PDM 支持通过在中央包存储库中安装相同的 wheel 包，并将该安装链接到不同项目中，来缓存安装。要启用它，请运行：

  1. pdm config install.cache on

它可以通过在命令中添加 --local 选项来按项目启用。

缓存位于 $(pdm config cache_dir)/packages。你可以使用 pdm cache info 查看缓存使用情况。请注意，缓存安装是自动管理的 —— 如果它们没有链接到任何项目，它们将被删除。从磁盘上手动删除缓存可能会破坏系统上的一些项目。

此外，支持几种链接到缓存条目的方法：

  • symlink（默认），为包文件创建符号链接。
  • hardlink，为缓存条目的包文件创建硬链接。

你可以通过运行 pdm config [-l] install.cache_method <method> 在它们之间切换。

!!! 注意 只有从 PyPI 解析的 命名需求 才能被缓存。

配置上传的存储库

当使用 pdm publish 命令时，它从 全局 配置文件(<CONFIG_ROOT>/config.toml) 中读取存储库密钥。配置内容如下：

  1. [repository.pypi]
  2. username = "frostming"
  3. password = "<secret>"
  5. [repository.company]
  6. url = "https://pypi.company.org/legacy/" 
  7. username = "frostming"
  8. password = "<secret>"
  9. ca_certs = "/path/to/custom-cacerts.pem"

或者，这些凭据也可以通过 env vars 提供：

  1. export PDM_PUBLISH_REPO=...
  2. export PDM_PUBLISH_USERNAME=...
  3. export PDM_PUBLISH_PASSWORD=...
  4. export PDM_PUBLISH_CA_CERTS=...

PEM 编码的证书颁发机构捆绑包 (ca_certs) 可用于本地 / 自定义 PyPI 存储库，其中服务器证书不是由标准 certifi CA 捆绑包签名的。

注意 存储库与前一节中的索引不同。存储库用于发布，而索引用于锁定和解析。它们不共享配置。

TIP 你不需要为 pypi 和 testpypi 存储库配置 url，它们已通过默认值填充。 用户名、密码和证书颁发机构捆绑包也可以通过 pdm publish 的 --username、--password 和 --ca-certs 分别从命令行传递。

要通过命令行更改存储库配置，请使用 pdm config 命令：

  1. pdm config repository.pypi.username "__token__"
  2. pdm config repository.pypi.password "my-pypi-token"
  4. pdm config repository.company.url "https://pypi.company.org/legacy/" 
  5. pdm config repository.company.ca_certs "/path/to/custom-cacerts.pem"

使用 keyring 管理密码

当 keyring 可用且受支持时，密码将存储到并从 keyring 中检索，而不是写入配置文件。这既支持索引也支持上传存储库。服务名称对于索引将是 pdm-pypi-<name>，对于存储库将是 pdm-repository-<name>。

你可以通过将 keyring 安装到与 PDM 相同的环境或全局安装来启用 keyring。要将 keyring 添加到 PDM 环境：

  1. pdm self add keyring

或者，如果你已全局安装了 keyring 的副本，请确保 CLI 在 PATH 环境变量中暴露，以便 PDM 可以发现它：

  1. export PATH=$PATH:path/to/keyring/bin

使用 keyring 管理 Azure Artifacts 的密码

当尝试对 azure artifacts 进行身份验证时，可以通过使用 AD 组进行身份验证来实现：pdm self add keyring artifacts-keyring 确保 artifacts-keyring 将用于身份验证。

然后在 pyproject.toml 中添加 artifacts url：

  1. [[tool.pdm.source]]
  2. name = "NameOfFeed"
  3. url = "https://pkgs.dev.azure.com/[org name]/_packaging/[feed name]/pypi/simple/"

覆盖解析的包版本

+++ 1.12.0

有时，由于上游库设置了你无法修复的错误版本范围，你可能无法获得依赖项解析。 在这种情况下，你可以使用 PDM 的覆盖功能，强制安装特定版本的包。

在 pyproject.toml 中的以下配置：

  1. [tool.pdm.resolution.overrides]
  2. asgiref = "3.2.10"  # 确切版本
  3. urllib3 = ">=1.26.2"  # 版本范围
  4. pytz = "https://mypypi.org/packages/pytz-2020.9-py3-none-any.whl"   # 绝对 URL

该表的每个条目都是一个包名称及其想要的版本。 在此示例中，PDM 将上述包解析为给定版本，无论是否有任何其他可用的解析。

!!! 警告 通过使用 [tool.pdm.resolution.overrides] 设置，你自己承担任何不兼容的风险。只有在没有对你的要求有效的解析，并且你知道特定版本可以工作时，才应使用它。 大多数时候，你可以只向 dependencies 数组添加任何临时约束。

从锁定文件中排除特定包及其依赖项

+++ 2.12.0

有时，你甚至不希望在锁定文件中包含某些包，因为你确信它们不会被任何代码使用。在这种情况下，你可以在依赖项解析期间完全跳过它们及其依赖项：

  1. [tool.pdm.resolution]
  2. excludes = ["requests"]

有了此配置，requests 将不会在锁文件中锁定，如果其他包不依赖它，它的依赖项如 urllib3 和 idna 也不会出现在解析结果中，安装程序也无法选择它们。

向每个 pdm 调用传递常量参数

+++ 2.7.0

你可以通过 tool.pdm.options 配置向个别 pdm 命令传递额外选项：

  1. [tool.pdm.options]
  2. add = ["--no-isolation", "--no-self"]
  3. install = ["--no-self"]
  4. lock = ["--no-cross-platform"]

这些选项将在命令名之后立即添加。根据上面的配置，pdm add requests 等同于 pdm add --no-isolation --no-self requests。

忽略包警告

+++ 2.10.0

在解析依赖项时，您可能会看到一些警告，例如：

  1. PackageWarning: Skipping scipy@1.10.0 because it requires Python
  2. <3.12,>=3.8 but the project claims to work with Python>=3.9.
  3. Narrow down the `requires-python` range to include this version. For example, ">=3.9,<3.12" should work.
  4.   warnings.warn(record.message, PackageWarning, stacklevel=1)
  5. Use `-q/--quiet` to suppress these warnings, or ignore them per-package with `ignore_package_warnings` config in [tool.pdm] table.

这是因为包支持的 Python 版本范围不包括 pyproject.toml 中指定的 requires-python 值。 你可以通过添加以下配置，在每个包的基础上忽略这些警告：

  1. [tool.pdm]
  2. ignore_package_warnings = ["scipy", "tensorflow-*"]

每个项目都是不区分大小写的 glob 模式，用于匹配包名称。