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

夢幻星辰

发布时间：2025-09-03 13:56:01

604人浏览过

来源于php中文网

原创

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

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

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

setuptools

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

wheel

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

sdist

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

解决方案

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

pyproject.toml

结合

build

工具。

项目结构准备： 一个典型的、推荐的项目结构会是这样：
```
my_project/
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── module_a.py
├── pyproject.toml
├── README.md
├── LICENSE
├── requirements.txt (可选，用于开发环境)
└── .gitignore
```
这里
```
src/
```
目录非常关键，它将你的包代码与项目根目录下的其他文件（如文档、测试、配置文件）清晰地分离。这避免了在开发模式下Python解释器意外地从项目根目录加载包的问题。

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免费学习笔记（深入）”；

安装构建工具： 你需要安装
```
build
```
工具来执行打包操作。
```
pip install build
```
执行打包： 在你的项目根目录（
```
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

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

Haiper

一个感知模型驱动的AI视频生成和重绘工具，提供文字转视频、图片动画化、视频重绘等功能

下载

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

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脚本更适合表达配置，结构清晰，易于阅读和维护。