whl文件名后缀

whl文件名后缀

1. Wheel 文件名的基本格式

Wheel 名称遵循 PEP 427 规范，通用格式为：

{distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl

• distribution：包名
• version：包版本
• build tag（可选）：构建号
• python tag：支持的 Python 解释器及版本
• abi tag：二进制兼容的 ABI（应用二进制接口）
• platform tag：目标操作系统和硬件平台

例子：

mypkg-1.2.3-1-cp39-cp39-manylinux2014_x86_64.whl
       │    │   │    │            └──── platform tag
       │    │   │    └──────────────── abi tag
       │    │   └─────────────────────── python tag
       │    └─────────────────────────── build tag
       └─────────────────────────────── distribution-version

---

2. build tag

• 格式：一个整数，有时候也会带字母或其他标识
• 用途：同一版本的多次编译时区分，比如针对不同源或依赖变动的二进制重构
• 示例：
  • mypkg-1.0-1-... 与 mypkg-1.0-2-... 表示同一版本的第 1 次和第 2 次构建

---

3. python tag

指明哪些 Python 解释器及版本可以安装该 Wheel。常见格式及含义：

tag 示例	含义
py3	支持所有 Python 3.x
py36 、py37…	专用于 Python 3.6、3.7 等
py2.py3	同时支持 Python 2.x 和 3.x
cp39	CPython 3.9
cp310	CPython 3.10
pp37	PyPy 3.7
jy37	Jython 2.7（标识为 jy27）等

• 前缀
  • py：纯 Python 实现
  • cp：CPython（二进制扩展）
  • pp：PyPy
  • jy：Jython

---

4. abi tag

ABI（Application Binary Interface）决定了编译的 C 扩展与解释器的二进制兼容性。常见 ABI tag：

tag 示例	含义
none	纯 Python 包，不含 C 扩展
abi3	使用了稳定的“limited API”（PEP 384），跨多个 CPython 版本兼容
cp39	针对 CPython 3.9 标准 ABI 编译
cp39m	CPython 3.9 + pymalloc enabled（m）
cp310d	CPython 3.10 Debug build（d）

• 如果 python tag 与 abi tag 一致（如 cp39-cp39），表示该包针对该版本的标准 ABI 编译
• 带后缀的如 m、d、u 等表示特定的编译选项

---

5. platform tag

描述该 Wheel 的目标操作系统、系统版本和 CPU 架构。常见平台 tag 及示例：

platform tag 示例	含义
manylinux1_x86_64	Linux x86_64，符合 Manylinux1 标准
manylinux2014_aarch64	Linux ARM64，符合 Manylinux2014 标准
win_amd64	Windows 64 位
win32	Windows 32 位
macosx_10_9_x86_64	macOS 10.9+ on x86_64
macosx_11_0_arm64	macOS 11+ on Apple Silicon (ARM64)
any	平台无关（纯 Python 包）

• manylinux 系列：用于在大多数 Linux 发行版上安装二进制扩展
• macosx：通常还会带上最低支持的 macOS 版本号
• any：完全纯 Python，无平台限制

---

6. 综合示例解析

Wheel 名称	解释
requests-2.28.1-py3-none-any.whl	纯 Python 包 requests v2.28.1，支持所有 Python 3，平台无关
numpy-1.24.0-cp39-cp39-manylinux2014_x86_64.whl	numpy v1.24.0，CPython 3.9 标准 ABI，Linux x86_64 二进制
Pillow-9.3.0-cp310-cp310-win_amd64.whl	Pillow v9.3.0，CPython 3.10，Windows 64 位
somepkg-0.1.0-2-cp38-abi3-manylinux1_x86_64.whl	somepkg v0.1.0，第 2 次构建，CPython 3.8 编译但使用 abi3，Linux x86_64

---

7. 为什么要了解这些后缀

1. 避免安装失败
   • pip install package.whl 时，若当前环境的 Python 版本、ABI 或平台与 Wheel 不匹配，安装会被跳过或报错。
2. 提高下载速度
   • 选择预编译好的 .whl，可免去源码编译时间，尤其是大型 C 扩展库（如 NumPy、SciPy）。
3. 跨平台兼容
   • 理解 manylinux、macosx、win 等标签，有助于在不同系统间无痛部署。

---

8. 查找可用的 Wheel

pip index versions PACKAGE_NAME

或

pip install PACKAGE_NAME --only-binary=:all:

• 第一个命令列出所有可用版本及对应的 Wheel
• 第二个命令强制只使用二进制 Wheel 安装