Python第三方库分发术语：Wheel、sdist与Egg格式详解

在日常使用 pip install 安装第三方扩展库或自己打包发布模块时，经常会遇到 .whl、.tar.gz 以及早已退出历史舞台的 .egg 文件。理解 Egg、sdist（Source Distribution）与 Wheel（Built Distribution）三种格式的定位、构成机制与底层差异，能够帮助开发者准确排查编译依赖缺失、包导入失败等问题，并规范现代 Python 软件包的构建与发布流程。

一、Python 包分发格式的历史演进与定位

Python 是一门解释型语言，但第三方库不仅包含纯 Python 源码（.py），还经常包含需要平台编译器处理的 C/C++ 扩展、外部动态链接库以及平台专有二进制文件。为了让这些库能够在不同操作系统与 Python 解释器间分发，Python 社区先后演进出了三种核心形态：

• Egg（历史格式）：由 Setuptools 于 2004 年引入，扩展名为 .egg，本质是包含代码与元数据的 zip 压缩包。它引入了依赖解析与运行时动态修改 sys.path 的机制，但缺乏严格的跨平台打包标准，且在安装时往往需要执行脚本，目前已被完全弃用。
• sdist（源码分发包）：Source Distribution 的缩写，通常为 .tar.gz 或 .zip 归档。它包含项目的原始源文件、资源文件以及构建元数据（如 pyproject.toml 或 setup.py）。客户端安装 sdist 时，必须在本地环境中触发构建与编译。
• Wheel（预编译/已构建分发包）：由 PEP 427 标准化确立，扩展名为 .whl。Wheel 是包含已准备就绪的文件及元数据的 zip 归档，安装时仅需解压复制到目标目录，完全绕过本地编译步骤。

图 1：Python 包格式的发展定位与代际演进示意

二、核心格式内部结构剖析

为了直观理解为什么 Wheel 安装不需要编译、为什么 sdist 具有完整源文件，我们可以解压观察它们的内部目录拓扑。

1. sdist（源码包）的目录结构

通过构建工具生成 sdist 时，其压缩包内不仅有纯 Python 代码，还包括测试用例、许可协议、C/C++ 头文件以及关键的构建配置描述文件：

example_package-1.0.0.tar.gz
└── example_package-1.0.0/
    ├── pyproject.toml         # 声明构建后端与打包规范 (PEP 517/518)
    ├── setup.py               # 传统的配置入口或扩展编译脚本
    ├── README.md              # 项目文档说明
    ├── LICENSE                # 许可证文件
    ├── PKG-INFO               # 打包时自动提取的元数据汇总
    ├── src/
    │   └── example/
    │       ├── __init__.py    # 模块代码
    │       └── core.c         # C 扩展源码（若存在）
    └── tests/                 # 测试用例文件

2. Wheel（已编译包）的目录结构

Wheel 本质是一个标准 ZIP 文件。其内部没有构建脚本，只有可以直接复制到 site-packages 的最终执行文件以及一个专用的元数据目录：

example_package-1.0.0-cp310-cp310-manylinux_2_17_x86_64.whl (zip 格式)
├── example/                   # 解压后直接进入 site-packages/
│   ├── __init__.py
│   └── core.cpython-310-x86_64-linux-gnu.so  # 已经预先编译好的二进制共享库
└── example_package-1.0.0.dist-info/          # 包元数据目录
    ├── METADATA               # 符合 PEP 566 的包描述与依赖项清单
    ├── WHEEL                  # 记录 Wheel 规范版本、构建标签及安装器信息
    ├── entry_points.txt       # 控制台入口命令定义 (CLI scripts)
    ├── top_level.txt          # 顶层包名称
    └── RECORD                 # 所有打包文件的 SHA256 哈希值与大小列表

其中的 RECORD 文件极其关键。它列出了压缩包内每个文件的相对路径和哈希签名。安装器（如 pip）在解压部署后，可以直接依据 RECORD 的记录实现安全完整性校验，并在执行 pip uninstall 时精确清理所有释放的文件，避免残留脏文件。

图 2：sdist 与 Wheel 内部文件组织与关键元数据对比

三、安装执行流程：Wheel 与 sdist 的生命周期

当开发者运行 pip install package_name 时，pip 会向 PyPI 索引查询匹配的包。如果索引中既有 Wheel 也有 sdist，pip 会优先下载适用于当前系统的 Wheel。这两种格式在目标主机上的安装链路存在本质区别：

1. Wheel 安装路径：免编译快速释放

Wheel 包是“构建完成态”。pip 下载 .whl 文件后，先校验文件名中的平台兼容标签，若匹配则直接解包将代码放入虚拟环境或系统的 site-packages，并解析 entry_points.txt 生成系统可执行脚本。整个流程耗时通常仅几十毫秒到几秒，完全不需要安装 gcc、clang、cmake 或对应 Python 版本的头文件（python3-dev）。

2. sdist 安装路径：隔离构建与环境依赖

若 PyPI 上没有匹配当前 Python 版本或操作系统的 Wheel，pip 只能回退下载 .tar.gz 源码包。此时系统会触发基于 PEP 517 的隔离构建：

1. 创建临时隔离环境：pip 会创建一个临时的虚拟构建沙箱。
2. 安装构建依赖：根据 pyproject.toml 中的 [build-system] requires 配置，下载安装构建所需的工具链（例如 setuptools、wheel、flit、hatchling、cython 等）。
3. 执行本地编译与构建：调用构建后端执行源码编译，生成一个临时的 Wheel 产物。
4. 最终解压部署：将生成的 Wheel 文件按照标准流程部署至 site-packages。

如果当前机器上缺乏 C 编译器、依赖的底层共享库缺失或头文件版本不兼容，sdist 安装流程会在第 3 步直接中断并报出常见的 Failed building wheel for ... 错误。

图 3：pip 处理 Wheel 与 sdist 时的具体决策分发路径

四、深入解析 Wheel 文件名命名规则

Wheel 文件名不是随意命名的，PEP 427 强制规定了五段式（或六段式）命名模板：

{distribution}-{version}(-{build_tag})?-{python_tag}-{abi_tag}-{platform_tag}.whl

例如：cryptography-41.0.3-cp37-abi3-manylinux_2_28_x86_64.whl

• distribution (cryptography)：第三方库名称，统一小写，连字符与下划线有规范要求。
• version (41.0.3)：遵循语义化版本规范的包版本号。
• python_tag (cp37)：兼容的 Python 实现与主次版本。例如 py2.py3 表示通用纯 Python；cp37 表示专为 CPython 3.7+ 构建。
• abi_tag (abi3)：应用二进制接口（ABI）标记。none 表示纯 Python，不需要特定 ABI；cp310 表示绑定特定 Python 3.10 的 C-API；而 abi3 则表示遵循 Python 的受限 C-API（Limited API），一个包可在 3.7 及以上所有新版本中通用运行。
• platform_tag (manylinux_2_28_x86_64)：支持的操作系统平台与 CPU 架构。常见的有 any（纯 Python）、win_amd64、macosx_11_0_arm64、manylinux2014_x86_64 等。

五、三种分发格式的关键技术特性对比

为了让不同场景下的选型更为清晰，以下在相同维度下对比三种格式的关键特性与影响：

图 4：现代 Python 包生态在发布与安装维度的总结实践矩阵

六、现代标准发布流程实践

在当前 Python 官方推荐的标准流程中，我们使用标准工具 build（PEP 517 推荐的前端工具）来统一生成 sdist 与 Wheel：

# 1. 安装标准化构建工具
python -m pip install --upgrade build

# 2. 在项目根目录执行打包（同时输出 sdist 和 Wheel）
python -m build

# 执行后在 dist/ 目录下将生成两个产物：
# dist/example_package-1.0.0.tar.gz
# dist/example_package-1.0.0-py3-none-any.whl

发布到 PyPI 时，同时上传 sdist 和 Wheel 是开源生态中最规范的做法。绝大多数用户会直接下载 Wheel 享受秒级无缝安装；而在某些缺少预编译二进制包的小众架构或特定系统发行版上，sdist 则作为坚实的基础保障，让用户依然能够在本地完成编译与运行。