创建 project

新项目

首先，使用 pdm init 创建一个新项目：

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 中保存的路径将被忽略。

使用 PDM 安装 Python 解释器

+++ 2.13.0

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

pdm python install 3.9.8

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

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

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

pdm python list

移除已安装的 Python 解释器：

pdm python remove 3.9.8

!!! TIP “与 Rye 共享安装”

PDM 使用与 [Rye](https://rye-up.com) 相同的源安装 Python 解释器。如果您同时使用 Rye，您可以将 `python.install_root` 指向与 Rye 相同的目录以共享 Python 解释器：
```bash
pdm config python.install_root ~/.rye/py
```
之后您可以使用 `rye toolchain` 或 `pdm python` 管理安装。

虚拟环境与否

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

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

关于这两种方法之间的区别，请参考文档中的相关部分：

• 虚拟环境
• __pypackages__(PEP 582)

库或应用程序

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

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

设置 requires-python 值

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

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

解析依赖项将导致 ResolutionImpossible：

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 定义的版本说明符。以下是一些示例：

使用旧版 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 无法工作。

请注意，如果您的项目是一个应用程序（即没有 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.with_pip 配置为 true 来实现，对于 __pypackages__，则使用 pdm add setuptools）

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

!!! 信息 转换 setup.py 将使用项目解释器执行该文件。确保 setuptools 已安装在解释器中，并且 setup.py 是可信的。

使用版本控制系统

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

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

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

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

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

显示当前 Python 环境

$ pdm info
PDM 版本：
  2.0.0
Python 解释器：
  /opt/homebrew/opt/python@3.9/bin/python3.9 (3.9)
项目根目录：
  /Users/fming/wkspace/github/test-pdm
项目包：
  /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"
}

这个命令 用于检查项目正在使用哪种模式：

• 如果 Project Packages 是 None，则启用了 virtualenv 模式。
• 否则，启用了 PEP 582 模式。

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