如何打包你的 Python 项目？setuptools 与 wheel

答案：python项目打包需用pyproject.toml定义元数据和依赖，结合setuptools生成wheel包，实现代码分发、依赖管理与跨环境部署，提升可维护性和协作效率。

打包Python项目，核心在于将其代码、依赖和元数据组织成一个可分发的格式，最常见的就是使用

setuptools

来定义项目结构，并通过它生成

wheel

格式的二进制分发包（以及

sdist

源码分发包），以便其他人或系统能轻松安装和使用。这不仅仅是为了上传到PyPI，更是为了项目自身的模块化、可维护性和协作效率。

解决方案

说实话，刚开始接触Python打包时，我个人觉得这玩意儿有点玄乎，各种配置文件和概念堆在一起。但一旦你理解了核心逻辑，它其实非常直观。现代Python项目的打包流程，强烈推荐使用

pyproject.toml

结合

build

工具。

1. 项目结构准备： 一个典型的、推荐的项目结构会是这样：

   my_project/ ├── src/ │   └── my_package/ │       ├── __init__.py │       └── module_a.py ├── pyproject.toml ├── README.md ├── LICENSE ├── requirements.txt (可选，用于开发环境) └── .gitignore

   这里

   src/

   目录非常关键，它将你的包代码与项目根目录下的其他文件（如文档、测试、配置文件）清晰地分离。这避免了在开发模式下Python解释器意外地从项目根目录加载包的问题。

2. pyproject.toml

   文件配置： 这是你的项目元数据和构建系统定义的核心文件。它遵循TOML格式，比传统的

   setup.py

   更声明式，更易于理解和维护。

   [build-system] requires = ["setuptools>=61.0", "wheel"] build-backend = "setuptools.build_meta"  [project] name = "my-awesome-package" version = "0.1.0" description = "一个超棒的Python项目，解决你的所有烦恼。" readme = "README.md" requires-python = ">=3.8" license = { file = "LICENSE" } keywords = ["awesome", "utility", "python"] authors = [     { name = "你的名字", email = "你的邮箱@example.com" }, ] maintainers = [     { name = "另一个贡献者", email = "另一个邮箱@example.com" }, ] classifiers = [     "Programming Language :: Python :: 3",     "License :: OSI Approved :: MIT License",     "Operating System :: OS Independent", ] dependencies = [     "requests>=2.28.1",     "numpy",     # 更多依赖... ]  [project.urls] "Homepage" = "https://github.com/你的用户名/my_project" "Bug Tracker" = "https://github.com/你的用户名/my_project/issues" "Documentation" = "https://my_project.readthedocs.io/"  [tool.setuptools.packages.find] where = ["src"] # 告诉setuptools在src目录下查找包

   这里我们定义了构建系统（使用

   setuptools

   作为后端），然后是项目的基本信息、依赖、作者、许可证等。

   [tool.setuptools.packages.find]

   部分是告诉

   setuptools

   去

   src

   目录下找你的python包。

   立即学习“Python免费学习笔记（深入）”；

3. 安装构建工具： 你需要安装

   build

   工具来执行打包操作。

   pip install build

4. 执行打包： 在你的项目根目录（

   pyproject.toml

   所在的目录）下运行：

   python -m build

   这个命令会执行构建过程，通常会在项目根目录下生成一个

   dist/

   目录。里面会包含两个文件：

   • my_awesome_package-0.1.0-py3-none-any.whl

     (Wheel 文件，二进制分发包)

   • my_awesome_package-0.1.0.tar.gz

     (Source Distribution，源码分发包)

现在，你就可以用

pip install dist/my_awesome_package-0.1.0-py3-none-any.whl

来安装你的包了，或者将其上传到PyPI。

为什么我的Python项目需要打包？

老实说，一开始我只是写脚本，本地跑跑，根本没想过打包这回事。但随着项目代码量上去，或者需要给别人用，甚至只是自己换台机器部署，就会发现不打包简直是自找麻烦。

核心原因在于：可重复性、可维护性和协作效率。

想想看，如果你写了一个工具，里面用到了

requests

、

pandas

这些库。如果只是把代码文件扔给别人，他们怎么知道要安装哪些依赖？版本对不对？打包就解决了这个问题。它把你的代码、依赖信息、版本号、作者、许可证等所有元数据都封装在一起，形成一个标准的、可安装的单元。

对于个人项目，打包意味着你可以轻松地在不同环境（比如开发机、测试服务器、生产环境）部署你的代码，确保依赖的一致性。对于团队协作，它提供了一个清晰的接口，让团队成员能够像使用任何第三方库一样使用你开发的模块，而不需要深入了解其内部结构。更重要的是，它为你的项目走向公开（比如发布到PyPI）铺平了道路，让全世界都能轻松地使用你的劳动成果。这不仅仅是技术上的必要，更是一种代码工程化和专业化的体现。

setuptools

与

wheel

：它们到底是什么关系？

理解

setuptools

和

wheel

的关系，就好比理解建筑师和预制板的关系。

setuptools

，你可以把它看作是项目的“建筑师”和“施工方”。它定义了你的项目应该如何被构建。它负责：

• 元数据管理：读取

  pyproject.toml

  （或

  setup.py

  ）中定义的项目名称、版本、作者、依赖等信息。

• 包发现：根据你的配置（比如

  where = ["src"]

  ），找到项目中实际的Python模块和包。

• 资源包含：确保像配置文件、数据文件等非Python代码也能被打包进去。
• 依赖解析：处理你项目所依赖的其他库。
• 构建指令：最终，它会执行一系列操作，将你的源代码和所有相关信息转换成可分发的格式。

简单来说，

setuptools

是那个知道如何把你的散乱代码和配置变成一个有组织的、可安装的“东西”的引擎。

而

wheel

，则是这个“东西”的最终“预制件”。它是一种二进制分发格式。想象一下，如果

setuptools

把你的项目“盖”好了，那么

wheel

就是那个已经打包好的、可以直接搬到工地上（你的Python环境里）安装的“预制房屋”。

它的特点是：

• 预编译：如果你的项目包含C扩展（例如

  numpy

  ），

  wheel

  文件通常会包含这些预编译好的二进制文件，省去了用户在安装时进行编译的步骤，大大加快了安装速度。

• 平台特定：一个

  wheel

  文件可能只适用于特定的Python版本和操作系统架构（尽管很多纯Python包是

  any

  ，即通用）。

• 安装快速：

  pip

  可以直接解压

  wheel

  文件并将其内容放置到正确的位置，无需执行任何构建步骤。

所以，它们的关系是：

setuptools

（作为构建后端）使用

wheel

格式来生成最终的可分发包。

setuptools

负责“制造”这个“预制件”，而

wheel

本身就是这个“预制件”的标准格式。当你运行

python -m build

时，

setuptools

会按照

pyproject.toml

的指示，最终输出

.whl

（以及

.tar.gz

）文件。

pyproject.toml

vs

setup.py

：我该选择哪一个？

这个问题，在我看来，几乎没有争议：强烈推荐使用

pyproject.toml

。

过去，

setup.py

是Python项目打包的黄金标准。它是一个python脚本，这意味着你可以用Python的全部灵活性来定义你的打包逻辑。你可以编写复杂的条件语句，动态地生成元数据，或者执行一些自定义的构建步骤。

# 示例：setup.py (不推荐，但了解一下) from setuptools import setup, find_packages  setup(     name="my_legacy_package",     version="0.1.0",     packages=find_packages(where="src"),     package_dir={"": "src"},     install_requires=[         "requests>=2.28.1",         "numpy",     ],     # ... 更多配置 )

然而，这种灵活性也带来了问题。

setup.py

需要被执行才能获取到项目的元数据，这使得工具链（比如

pip

）在处理它时变得复杂。它可能引入副作用，或者依赖于特定的Python环境才能正确运行。这导致了所谓的“构建隔离”问题，即构建工具本身可能需要依赖项目本身的依赖才能运行，形成循环依赖。

而

pyproject.toml

，则是Python打包生态系统迈向现代化的关键一步（通过PEP 517和PEP 518）。它是一个声明式的配置文件，用TOML格式编写。这意味着：

• 元数据是静态的：工具可以在不执行任何Python代码的情况下，直接解析

  pyproject.toml

  来获取项目的元数据。这大大简化了构建工具的工作。

• 构建系统隔离：

  pyproject.toml

  明确定义了构建项目所需的工具（如

  setuptools

  和

  wheel

  ），这些工具会在一个隔离的环境中安装和运行，避免了与项目运行时依赖的冲突。

• 标准化：它提供了一个统一的入口点，不仅

  setuptools

  可以使用，像

  Poetry

  、

  Flit

  这样的替代构建工具也可以使用。

• 更清晰：TOML格式本身就比Python脚本更适合表达配置，结构清晰，易于阅读和维护。

尽管

setup.py

仍然被大量遗留项目使用，并且在某些极度复杂的定制化构建场景下可能仍有其用武之地，但对于绝大多数新项目和现有项目的迁移，

pyproject.toml

都是毫无疑问的最佳选择。它代表了Python打包的未来，提供了更健壮、更可预测、更易于管理的构建体验。我的建议是，从一开始就拥抱

pyproject.toml

，你会省去很多不必要的麻烦。