工具推荐#

Python 打包领域包含许多不同的工具。对于许多任务，Python 打包机构（PyPA，一个涵盖许多打包工具并维护本指南的工作组）故意不提出全面建议；例如，存在许多构建后端的原因是，该领域已开放，以便能够开发新的后端，以更好地满足某些用户的需求，而不是以前唯一的后端 setuptools。本指南确实指出了得到广泛认可的一些工具，并对你不应使用的工具提出了一些建议，因为它们已弃用或不安全。

虚拟环境#

手动创建和使用虚拟环境的标准工具是 virtualenv（PyPA 项目）和 venv（Python 标准库的一部分，尽管缺少 virtualenv 的一些功能）。

安装包#

pip 是从 PyPI 安装包的标准工具。你可能需要阅读 pip 关于 安全安装 的建议。Pip 通过标准库包 ensurepip 在大多数 Python 安装中默认提供。

或者，考虑使用 pipx，用于安装通过 PyPI 分发并从命令行运行的 Python 应用程序的特定用例。Pipx 是 pip 和 venv 的一个包装器，它将每个应用程序安装到一个专门的虚拟环境中。这避免了不同应用程序的依赖项之间的冲突，也避免了与使用相同 Python 解释器的系统级应用程序之间的冲突（尤其是在 Linux 上）。

对于科学软件，请考虑 conda 或 Spack。

待办事项

在此处或新讨论中撰写“pip 与 Conda”比较。

不要使用 easy_install（Setuptools 的一部分），它已被弃用，转而使用 pip（有关详细信息，请参阅 pip 与 easy_install）。同样，不要使用 python setup.py install 或 python setup.py develop，它们也已弃用（有关背景信息，请参阅 setup.py 已弃用？，有关迁移建议，请参阅 如何使基于 setup.py 的项目现代化？）。

锁定文件#

pip-tools 和 Pipenv 是两个公认的工具，用于创建锁定文件，其中包含为重现性目的安装到环境中的所有包的确切版本。

构建后端#

重要提示

请记住：本文件不寻求引导读者使用特定工具，而只是枚举常见工具。不同的用例通常需要专门的工作流。

纯 Python 包的热门 构建后端按字母顺序排列如下

  • Flit-core – 与 flit 共同开发，但独立于 flit。一个极简且有主见的构建后端。不支持插件。

  • Hatchling – 与 hatch 共同开发，但独立于 hatch。支持插件。

  • PDM-backend – 与 pdm 共同开发，但独立于 pdm。支持插件。

  • Poetry-core – 与 poetry 共同开发，但独立于 poetry。支持插件。

    与列表中的其他后端不同，Poetry-core 不支持标准 [project] 表（它使用不同的格式，在 [tool.poetry] 表中）。

  • Setuptools，曾经是唯一的构建后端。支持插件。

    警告

    如果您使用 setuptools，请注意，一些早于标准化工作的功能现在已被弃用，并且仅暂时保留以保持兼容性。

    特别是，不要使用直接 python setup.py 调用。另一方面，使用 setup.py 文件配置 setuptools 仍然得到完全支持，尽管建议尽可能使用现代 pyproject.toml 中的 [project] 表（或 setup.cfg），并且仅在需要编程配置时保留 setup.py。请参阅 setup.py 是否已弃用？。

    您不应使用的其他弃用功能示例包括 setup() 中的 setup_requires 参数（改为使用 pyproject.toml 中的 [build-system] 表），以及 easy_install 命令（请参阅 pip 与 easy_install）。

不要使用 distutils，它已弃用，并且已从 Python 3.12 中的标准库中删除，尽管它仍然可以通过 setuptools 获得。

对于具有 扩展模块 的包，最好使用专门支持扩展所写语言的构建系统，例如

  • Setuptools – 本机支持 C 和 C++（使用第三方插件支持 Go 和 Rust），

  • meson-python – C、C++、Fortran、Rust 和 Meson 支持的其他语言，

  • scikit-build-core – C、C++、Fortran 和 CMake 支持的其他语言，

  • Maturin – 通过 Cargo 支持 Rust。

构建发行版#

用于构建 源发行版 和 轮子 以上传到 PyPI 的标准工具是 build。它将调用您在 pyproject.toml 中 声明 的任何构建后端。

不要使用 python setup.py sdist 和 python setup.py bdist_wheel 执行此任务。所有直接调用 setup.py 的行为都已 弃用。

如果您有 扩展模块 并希望为多个平台分发轮子，请使用 cibuildwheel 作为 CI 设置的一部分来构建可分发的轮子。

上传到 PyPI#

对于在 GitHub 上托管的项目，建议使用 受信任的发布，它允许从 GitHub Actions 作业安全地将包上传到 PyPI。（目前尚不支持 GitHub 以外的其他软件平台。）

另一种可用方法是使用 twine 手动上传包。

切勿使用 python setup.py upload 执行此任务。除了 弃用 之外，它也不安全。

工作流工具#

这些工具是环境管理器，可自动管理项目的虚拟环境。它们还充当“任务运行器”，允许您定义和调用任务，例如运行测试、编译文档、重新生成某些文件等。其中一些工具提供了用于构建发行版和上传到 PyPI 的快捷方式，而另一些则支持应用程序的锁定文件。它们通常会隐式调用上面提到的工具。按字母顺序排列