Skip to content

新建项目#

首先，使用以下命令 pdm init 创建一个新项目：

1
2
mkdir my-project && cd my-project
pdm init

您需要回答几个问题，以帮助 PDM 为您创建 pyproject.toml 文件。 有关 pdm init 更多用法，请阅读 从模板创建项目。

选择 Python 解释器#

首先，您需要从已安装在您的计算机上的 Python 版本列表中选择一个 Python 解释器。 解释器路径将被存储在 .pdm-python 文件中，并在后续命令中使用。您还可以稍后使用 pdm use命令更改它。

或者，您可以通过 PDM_PYTHON环境变量指定 Python 解释器路径。设置后，保存的 .pdm-python 路径将被忽略。

使用现有环境

如果您选择使用现有环境，例如重复使用由 conda 创建的环境，请注意，在运行 pdm sync --clean 或 pdm remove 时，PDM 将 删除 未在 pyproject.toml 或 pdm.lock 中列出的依赖项。这可能会导致破坏性后果。因此，尽量不要在多个项目之间共享环境。

使用 PDM 安装 Python 解释器#

在版本 2.13.0 中添加

PDM 支持使用命令 pdm python install 从 @indygreg's python-build-standalone 安装其他 Python 解释器。 例如，要安装 CPython 3.9.8：

1
pdm python install 3.9.8

您可以使用 pdm python install --list 查看所有可用的 Python 版本。

这会将 Python 解释器安装到 python.install_root 配置指定的位置。

列出当前安装的 Python 解释器：

1
pdm python list

删除已安装的 Python 解释器：

1
pdm python remove 3.9.8

与 Rye 共享安装

PDM 使用与 Rye 相同的源来安装 Python 解释器。如果您同时使用 Rye，则可以将 python.install_root 指向与 Rye 相同的目录以共享 Python 解释器：

1
pdm config python.install_root ~/.rye/py

之后，您可以使用 rye toolchain 或 pdm python来管理安装。

基于 'requires-python' 的安装策略#

在版本 2.16.0 中添加

如果未给出 Python version，PDM 将尝试安装当前平台/架构组合的最佳匹配项 基于 pyproject.toml 中的 requires-python （如果 pyproject.toml 或 requires-python 属性不可用， 考虑所有可安装的 Python 解释器）。

默认策略为“最大”，即将安装最高的 cPython 解释器版本。

如果首选 minimum，请使用选项 --min 并将 version 留空。

1
pdm python install --min

同样的原则也适用于[pdm use]（../reference/cli.md#use） （包括自动安装功能） 这使它成为 CI/CD 或“使用现有 pyproject.toml 重新开始”用例的良好无人值守设置命令。

是否使用虚拟环境#

选择 Python 解释器后，PDM 将询问您是否要为项目创建虚拟环境。 如果选择 是，PDM 将在项目根目录中创建一个虚拟环境，并将其用作项目的 Python 解释器。

如果所选的 Python 解释器位于虚拟环境中，PDM 会将其用作项目环境，并在其中安装依赖项。 否则，__pypackages__ 将在项目根目录中创建，并将依赖项安装到其中。

有关这两种方法的区别，请参阅文档中的相应部分：

库或应用程序#

库和应用程序在许多方面有所不同。简而言之，库是旨在由其他项目安装和使用的包。在大多数情况下，它还需要上传到 PyPI。另一方面，应用程序是直接面向最终用户的应用程序，可能需要部署到某些生产环境中。

在PDM中，如果选择创建一个库，PDM 会向 pyproject.toml 文件添加 name、version 字段，以及一个 build backend 表格用于构建后端，这只有在您的项目需要构建和分发时才有用。因此，如果您想将项目从应用程序更改为库，您需要手动添加这些字段到 pyproject.toml 中。此外，当您运行 pdm install 或 pdm sync 时，库项目将被安装到环境中，除非指定了--no-self。

在 pyproject.toml 中，在 [tool.pdm] 表下有一个字段 distribution。如果将其设置为 true ，PDM 将把该项目视为一个库。

指定 requires-python#

您需要为项目设置适当的 requires-python 值。这是一个重要属性，会影响依赖关系的解析方式。基本上，每个包 requires-python 都必须_涵盖_项目的 requires-python 范围。例如，请考虑以下设置：

  • 项目: requires-python = ">=3.9"
  • 包 foo: requires-python = ">=3.7,<3.11"

解析依赖关系将导致 Resolution Impossible 错误:

1
2
Unable to find a resolution because the following dependencies don't work
on all Python versions defined by the project's `requires-python`

因为依赖项 requires-python 是 >=3.7,<3.11，所以它 不 涵盖项目的 requires-python 范围 >=3.9。换句话说，该项目承诺在 Python 3.9、3.10、3.11（等）上运行，但依赖项不支持 Python 3.11（或更高版本）。由于 PDM 创建了一个跨平台锁定文件，该文件应适用于 requires-python 该范围内的所有 Python 版本，因此它找不到有效的解决方案。 要解决此问题，您需要将最大版本添加到 requires-python 中，例如 >=3.9,<3.11。

requires-python 的值是根据 PEP 440定义的版本指定符。以下是一些示例：

requires-python 含义
>=3.7 Python 3.7 及更高版本
>=3.7,<3.11 Python 3.7, 3.8, 3.9 和 3.10
>=3.6,!=3.8.*,!=3.9.* Python 3.6 及更高版本，3.8 和 3.9 除外

使用较旧的 Python 版本#

在版本 2.19.0 中移除

PDM 现在支持 3.8 及更高版本作为项目的 python 版本。

尽管 PDM 在 Python 3.8 及更高版本上运行，但您仍然可以为 工作项目 使用较低的 Python 版本。但请记住，如果你的项目是一个需要构建、发布或安装的库，你要确保正在使用的 PEP 517 构建后端支持你需要的最低 Python 版本。例如，默认后端 pdm-backend 仅适用于 Python 3.7+，因此如果您在使用 Python 3.6 的项目上运行 pdm build，则会收到错误。大多数现代构建后端都放弃了对 Python 3.6 及更低版本的支持，因此强烈建议将 Python 版本升级到 3.7+。以下是一些常用构建后端支持的 Python 范围，我们只列出那些支持 PEP 621 的后端，否则 PDM 无法使用它们。

Backend 支持的 Python 支持 PEP 621
pdm-backend >=3.7 Yes
setuptools>=60 >=3.7 Experimental
hatchling >=3.7 Yes
flit-core>=3.4 >=3.6 Yes
flit-core>=3.2,<3.4 >=3.4 Yes

请注意，如果您的项目是应用程序（即没有 name 元数据），则上述后端限制不适用。 因此，如果您不需要构建后端，则可以使用任何 Python 版本 >=2.7。

从其他包管理器导入项目#

如果您已经在使用其他包管理器工具，如 Pipenv 或 Poetry，则很容易迁移到 PDM。 PDM 提供了 import 命令，因此您不必手动初始化项目，它现在支持：

  1. Pipenv Pipfile
  2. Poetry 的 pyproject.toml 部分
  3. Flit 的 pyproject.toml 部分
  4. pip 使用的格式 requirements.txt
  5. setuptools setup.py（它要求在项目环境中安装 setuptools。您可以通过为venv配置 venv.with_pip 为 true，并为 __pypackages__ 添加 pdm add setuptools 来实现此目的）

此外，当您执行 pdm init 或 pdm install 时，如果您的 PDM 项目尚未初始化，PDM 可以自动检测可能要导入的文件。

Info

转换一个 setup.py 将使用项目解释器执行文件。确保 setuptools与解释器一起安装，并且 是可信的 setup.py。

使用版本控制#

您 必须 提交 pyproject.toml 文件。您应该提交 pdm.lock 和 pdm.toml 文件。不要 commit 提交 .pdm-python 文件。

必须提交该 pyproject.toml 文件，因为它包含项目的构建元数据和 PDM 所需的依赖项。 它也通常被其他 python 工具用于配置。 在 Pip 文档 中阅读有关该 pyproject.toml 文件的更多信息。

您应该提交文件 pdm.lock ，这样可以确保所有安装程序都使用相同版本的依赖项。 若要了解如何更新依赖项，请参阅 更新现有依赖项。

pdm.toml 包含一些项目范围的配置，提交它以供共享可能很有用。

.pdm-python 存储当前项目使用的 Python 路径，不需要 共享。

显示当前 Python 环境#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
$ pdm info
PDM version:
  2.0.0
Python Interpreter:
  /opt/homebrew/opt/[email protected]/bin/python3.9 (3.9)
Project Root:
  /Users/fming/wkspace/github/test-pdm
Project Packages:
  /Users/fming/wkspace/github/test-pdm/__pypackages__/3.9

# 查看虚拟环境信息
$ pdm info --env
{
  "implementation_name": "cpython",
  "implementation_version": "3.8.0",
  "os_name": "nt",
  "platform_machine": "AMD64",
  "platform_release": "10",
  "platform_system": "Windows",
  "platform_version": "10.0.18362",
  "python_full_version": "3.8.0",
  "platform_python_implementation": "CPython",
  "python_version": "3.8",
  "sys_platform": "win32"
}

pdm info 这个命令可用于检查项目正在使用的模式：

现在，您已经设置了一个新的 PDM 项目并获取了一个 pyproject.toml 文件。 请参阅元数据部分，了解如何正确编写 pyproject.toml。