Python 包发布深度解析：wheel 与 sdist 到底有什么区别？从构建、安装到生产部署全面理解 Python 分发机制

原创于 2026-09-20 11:13:12 发布 · 28 阅读

1 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

学习笔记

课程教程

提升学习

话题

#开学季·九月创作之星博客挑战赛

Python 包发布深度解析：wheel 与 sdist 到底有什么区别？从构建、安装到生产部署全面理解 Python 分发机制

关键词：Python编程、Python教程、Python实战、Python最佳实践、Python包发布、wheel、sdist、pip安装机制

在 Python 生态中，很多开发者都会使用：

pip install mypkg

来安装第三方库。

然而，当我们真正参与 Python 项目开发、维护企业级服务，甚至发布自己的开源包时，会遇到一个非常关键的问题：

我发布到 PyPI 的到底是什么？
为什么一个包同时有 .tar.gz 和 .whl 两种格式？
为什么有时候安装很快，有时候却需要本地编译？
为什么 C 扩展包安装失败，经常提示缺少编译环境？

这些问题的核心，就在 Python 的软件分发格式（distribution format）。

目前 Python 生态中最重要的两种发布格式：

sdist（source distribution，源码分发包）
wheel（二进制分发包）

理解它们，不仅能帮助你解决安装问题，更能帮助你构建更稳定、更专业的 Python 工程体系。

一、Python 包发布的完整生命周期

在理解 wheel 和 sdist 之前，我们先看一个 Python 包从开发到用户安装的大致流程：

开发源码
    |
    |
    v
项目构建(Build)
    |
    +----------------+
    |                |
    v                v
 sdist            wheel
源码包             二进制包
.tar.gz            .whl
    |                |
    +----------------+
             |
             v
          PyPI仓库
             |
             v
        pip install
             |
             v
        用户环境

例如：

你的项目：

mypkg/
├── pyproject.toml
├── src/
│   └── mypkg/
│       ├── __init__.py
│       └── core.py
└── README.md

执行：

python -m build

生成：

dist/
├── mypkg-1.2.0.tar.gz
└── mypkg-1.2.0-py3-none-any.whl

这两个文件，就是本文讨论的重点。

二、什么是 sdist？

1. sdist 的本质

sdist：

Source Distribution（源码分发包）

它包含的是：

你的 Python 项目源代码。

例如：

mypkg-1.2.0.tar.gz

解压：

tar -zxvf mypkg-1.2.0.tar.gz

可能看到：

mypkg-1.2.0/

├── pyproject.toml
├── setup.py
├── README.md
├── src/
│   └── mypkg/
│       ├── __init__.py
│       └── utils.py
└── tests/

里面就是开发者写的代码。

2. 安装 sdist 的过程

假设：

用户执行：

pip install mypkg-1.2.0.tar.gz

流程：

下载源码包

      |
      v

解压源码

      |
      v

读取构建配置

(pyproject.toml)

      |
      v

创建wheel

      |
      v

安装wheel

      |
      v

完成安装

也就是说：

pip 通常不会直接运行源码包，而是先把 sdist 转换成 wheel。

例如：

pip install numpy.tar.gz

可能发生：

源码
 |
 |
 v
编译
 |
 |
 v
生成安装文件
 |
 |
 v
安装

因此 sdist 最大的问题：

用户机器需要具备完整构建环境。

包括：

Python 开发头文件
C 编译器
系统库
编译工具链

三、什么是 wheel？

1. wheel 的本质

wheel：

Python 官方推荐的二进制分发格式。

文件：

mypkg-1.2.0-py3-none-any.whl

实际上：

.whl

就是一个 ZIP 文件。

可以查看：

unzip mypkg-1.2.0-py3-none-any.whl

内容：

mypkg/
├── __init__.py
├── core.py

mypkg-1.2.0.dist-info/
├── METADATA
├── RECORD
└── WHEEL

wheel 最大特点：

已经构建完成，可以直接安装。

安装：

pip install mypkg-1.2.0-py3-none-any.whl

流程：

下载wheel

    |
    v

解压文件

    |
    v

复制到site-packages

    |
    v

完成

没有：

编译
构建
配置环境

速度非常快。

四、wheel 文件名是什么意思？

来看：

mypkg-1.2.0-py3-none-any.whl

拆开：

mypkg
 |
项目名称


1.2.0
 |
版本


py3
 |
Python版本


none
 |
ABI兼容


any
 |
平台

1. py3

表示：

支持 Python 3。

例如：

mypkg-1.0-py3-none-any.whl

可以：

Python 3.8
Python 3.9
Python 3.10
Python 3.11

2. none

表示：

没有特殊 ABI 依赖。

ABI：

Application Binary Interface

即：

二进制接口。

3. any

表示：

任何操作系统。

例如：

同一个 wheel：

Windows
Linux
macOS

都能安装。

五、sdist 和 wheel 的核心区别

总结：

对比	sdist	wheel
类型	源码包	二进制包
文件格式	.tar.gz	.whl
内容	源代码	已构建文件
是否需要编译	可能需要	通常不需要
安装速度	慢	快
平台依赖	无	可能有
用户体验	较差	更好
发布推荐	保留	优先提供

六、为什么 C Extension wheel 与平台相关？

这是很多高级 Python 开发者必须理解的问题。

Python 本身：

.py

天然跨平台。

例如：

def add(a,b):
    return a+b

Windows：

可以运行。

Linux：

可以运行。

macOS：

可以运行。

但是：

很多高性能 Python 库不是纯 Python。

例如：

NumPy
Pandas
PyTorch
OpenCV

内部大量使用：

Python
 +
C/C++
 +
Fortran

例如：

Python代码：

import numpy

numpy.array([1,2,3])

实际上调用：

Python

  |
  v

C Extension

  |
  v

CPU指令

于是 wheel 里面可能包含：

numpy/

├── core.py

└── _multiarray_umath.so

这个：

.so

是 Linux 动态库。

Windows：

.pyd

macOS：

.dylib

不同系统无法通用。

因此：

一个 C 扩展 wheel：

必须标记平台。

例如：

numpy-2.0.0-cp311-cp311-manylinux_x86_64.whl

含义：

cp311

支持Python 3.11


manylinux

Linux兼容标准


x86_64

CPU架构

七、manylinux 到底解决什么？

这是 Python 包生态中非常重要的一项技术。

1. 问题来源

Linux 世界非常碎片化：

例如：

服务器可能：

Ubuntu 20.04

CentOS 7

Debian 11

Amazon Linux

每个平台：

glibc版本不同。

如果开发者：

在 Ubuntu 编译：

extension.so

然后上传：

可能：

Ubuntu 能运行。

CentOS：

失败。

错误：

GLIBC_2.34 not found

2. manylinux 出现

manylinux 是：

Python 官方定义的一套 Linux wheel 兼容标准。

目标：

让一个 wheel：

可以运行更多 Linux 系统。

例如：

mypkg-1.0-cp311-manylinux2014_x86_64.whl

表示：

符合 manylinux2014 标准。

构建过程：

Docker环境

manylinux镜像

      |
      v

编译C扩展

      |
      v

生成wheel

      |
      v

上传PyPI

开发者通常使用：

cibuildwheel 官方项目

自动构建多平台 wheel。

八、为什么生产环境更偏爱预构建 wheel？

这是企业工程实践中的重点。

假设：

线上服务器部署：

100台机器

安装：

pip install myservice

如果依赖：

pandas
numpy
cryptography

全部从源码编译：

问题：

1. 部署速度慢

源码：

下载

↓

编译

↓

链接

↓

安装

可能：

几十分钟。

wheel：

下载

↓

安装

↓

完成

几秒。

2. 环境不稳定

源码编译依赖：

gcc

make

python-dev

openssl-dev

生产服务器未必安装。

导致：

error:
command 'gcc' failed

3. 难以保证一致性

源码编译：

不同机器：

机器A

gcc 9


机器B

gcc 11

可能产生：

不同结果。

wheel：

提前构建：

开发环境

↓

测试

↓

发布wheel

↓

生产安装

更加可控。

九、实际项目发布示例

下面创建一个简单 Python 包。

demo_pkg/

├── pyproject.toml

├── src/

│   └── demo_pkg/

│       ├── __init__.py

│       └── hello.py

hello.py：

def hello(name):
    return f"Hello {name}"

构建

安装工具：

pip install build

执行：

python -m build

输出：

dist/

├── demo_pkg-1.0.tar.gz

└── demo_pkg-1.0-py3-none-any.whl

上传 PyPI

安装：

pip install twine

上传：

twine upload dist/*

用户：

pip install demo_pkg

pip 会：

优先寻找：

wheel

如果不存在：

才考虑：

sdist

十、如何选择发布策略？

纯 Python 项目

例如：

requests

flask

fastapi

C/C++ 扩展项目

例如：

opencv

numpy

pytorch

必须：

提供：

多个平台wheel

例如：

Linux

Windows

macOS

不同：

Python版本

CPU架构

十一、生产级 Python 包最佳实践

1. 永远发布 wheel

现代 Python 项目：

不要只上传：

.tar.gz

至少：

.whl

.tar.gz

2. 使用 pyproject.toml

现代标准：

[build-system]
requires=[
    "setuptools",
    "wheel"
]

build-backend="setuptools.build_meta"

替代：

旧：

setup.py

3. 自动化构建

4. 测试不同环境

例如：

Python 3.9

Python 3.10

Python 3.11

Linux

Windows

macOS

十二、常见问题排查

问题1：

Could not build wheels for xxx

原因：

没有匹配 wheel。

pip 被迫源码编译。

解决：

升级：

pip install -U pip setuptools wheel

或者：

安装系统依赖。

问题2：

No matching distribution found

原因：

没有对应平台 wheel。

例如：

你的环境：

Python 3.12

但是包只提供：

cp311

问题3：

Linux安装失败：

GLIBC_xxx not found

原因：

wheel 不兼容。

检查：

pip debug --verbose

十三、未来趋势：Python 分发体系会越来越成熟

Python 生态正在从：

过去：

下载源码
本地编译
安装

逐渐转向：

预构建wheel

↓

快速部署

↓

可靠运行

这也是为什么：

现代云原生环境：

Docker：

Kubernetes：

Serverless：

都高度依赖 wheel。

总结：理解 wheel 与 sdist，是成为高级 Python 工程师的重要一步

很多初学者认为：

Python 包发布就是：

pip install

但真正成熟的软件工程，需要理解：

源码如何变成发行包？

发行包如何安装？

为什么某些包需要编译？

如何保证生产环境稳定？

简单总结：

场景	推荐
开发阶段	sdist + wheel
普通 Python 库	universal wheel
企业生产部署	优先 wheel
C 扩展项目	多平台 wheel
Linux生态	manylinux wheel

掌握 wheel 和 sdist，不只是解决一个安装问题，而是理解 Python 软件供应链的重要一步。

Python 包发布深度解析：wheel 与 sdist 到底有什么区别？从构建、安装到生产部署全面理解 Python 分发机制

Python 包发布深度解析：wheel 与 sdist 到底有什么区别？从构建、安装到生产部署全面理解 Python 分发机制

一、Python 包发布的完整生命周期

二、什么是 sdist？

1. sdist 的本质

2. 安装 sdist 的过程

三、什么是 wheel？

1. wheel 的本质

四、wheel 文件名是什么意思？

1. py3

2. none

3. any

五、sdist 和 wheel 的核心区别

六、为什么 C Extension wheel 与平台相关？

七、manylinux 到底解决什么？

1. 问题来源

2. manylinux 出现

八、为什么生产环境更偏爱预构建 wheel？

1. 部署速度慢

2. 环境不稳定

3. 难以保证一致性

九、实际项目发布示例

构建

上传 PyPI

十、如何选择发布策略？

纯 Python 项目

C/C++ 扩展项目

十一、生产级 Python 包最佳实践

1. 永远发布 wheel

2. 使用 pyproject.toml

3. 自动化构建

4. 测试不同环境

十二、常见问题排查

问题1：

问题2：

问题3：

十三、未来趋势：Python 分发体系会越来越成熟

总结：理解 wheel 与 sdist，是成为高级 Python 工程师的重要一步

推荐学习资料