使用最小配置在 CI 中构建 Python 轮子。
项目描述
cibuildwheel
Python 轮子很棒。在 Mac, Linux, Windows 上，在多个 Python 版本上构建它们，就不是那么简单了。
cibuildwheel 就是为此而生的。它运行在您的 CI 服务器上——目前支持 GitHub Actions、Azure Pipelines、Travis CI、AppVeyor、CircleCI 和 GitLab CI——并在所有平台上构建和测试您的轮子。
它做什么？
| macOS Intel | macOS Apple Silicon | Windows 64位 | Windows 32位 | Windows Arm64 | manylinux musllinux x86_64 |
manylinux musllinux i686 |
manylinux musllinux aarch64 |
manylinux musllinux ppc64le |
manylinux musllinux s390x |
musllinux armv7l | Pyodide | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| CPython 3.6 | ✅ | N/A | ✅ | ✅ | N/A | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A |
| CPython 3.7 | ✅ | N/A | ✅ | ✅ | N/A | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A |
| CPython 3.8 | ✅ | ✅ | ✅ | ✅ | N/A | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A |
| CPython 3.9 | ✅ | ✅ | ✅ | ✅ | ✅² | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A |
| CPython 3.10 | ✅ | ✅ | ✅ | ✅ | ✅² | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A |
| CPython 3.11 | ✅ | ✅ | ✅ | ✅ | ✅² | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A |
| CPython 3.12 | ✅ | ✅ | ✅ | ✅ | ✅² | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅⁴ |
| CPython 3.13³ | ✅ | ✅ | ✅ | ✅ | ✅² | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A |
| PyPy 3.7 v7.3 | ✅ | N/A | ✅ | N/A | N/A | ✅¹ | ✅¹ | ✅¹ | N/A | N/A | N/A | N/A |
| PyPy 3.8 v7.3 | ✅ | ✅ | ✅ | N/A | N/A | ✅¹ | ✅¹ | ✅¹ | N/A | N/A | N/A | N/A |
| PyPy 3.9 v7.3 | ✅ | ✅ | ✅ | N/A | N/A | ✅¹ | ✅¹ | ✅¹ | N/A | N/A | N/A | N/A |
| PyPy 3.10 v7.3 | ✅ | ✅ | ✅ | N/A | N/A | ✅¹ | ✅¹ | ✅¹ | N/A | N/A | N/A | N/A |
¹ PyPy 仅支持 manylinux 轮子。
² Windows arm64 支持是实验性的。
³ CPython 3.13 默认使用 Python RCs 构建，从 cibuildwheel 2.20 开始。免费线程模式仍然需要通过 CIBW_FREE_THREADED_SUPPORT 进行选择。
⁴ 实验性，目前不在 PyPI 上支持，但可以直接用于网络部署。使用 --platform pyodide 构建。
- 为 CPython 和 PyPy 构建 manylinux、musllinux、macOS 10.9+ 和 Windows 轮子
- 在 GitHub Actions、Azure Pipelines、Travis CI、AppVeyor、CircleCI、GitLab CI 和 Cirrus CI 上运行
- 通过 auditwheel 和 delocate 在 Linux 和 macOS 上捆绑共享库依赖项
- 针对通过轮子安装的库版本运行您的库的测试
如果您需要构建不支持的 Python 版本，如 Python 2，请参阅 cibuildwheel 1 文档。
用法
cibuildwheel 在 CI 服务中运行。支持的平台取决于您使用的是哪个服务
| Linux | macOS | Windows | Linux ARM | macOS ARM | Windows ARM | |
|---|---|---|---|---|---|---|
| GitHub Actions | ✅ | ✅ | ✅ | ✅¹ | ✅ | ✅² |
| Azure Pipelines | ✅ | ✅ | ✅ | ✅ | ✅² | |
| Travis CI | ✅ | ✅ | ✅ | |||
| AppVeyor | ✅ | ✅ | ✅ | ✅ | ✅² | |
| CircleCI | ✅ | ✅ | ✅ | ✅ | ||
| Gitlab CI | ✅ | ✅ | ✅ | ✅¹ | ✅ | |
| Cirrus CI | ✅ | ✅ | ✅ | ✅ | ✅ |
¹ 需要仿真，单独分发。其他服务也可能通过仿真或第三方构建宿主支持 Linux ARM，但这些在我们的 CI 中未进行测试。
² 使用交叉编译。在此 CI 平台上无法测试 arm64。
示例设置
要在 GitHub Actions 上构建 manylinux、musllinux、macOS 和 Windows 轮子，您可以使用这个 .github/workflows/wheels.yml
name: Build
on: [push, pull_request]
jobs:
build_wheels:
name: Build wheels on ${{ matrix.os }}
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-13, macos-14]
steps:
- uses: actions/checkout@v4
# Used to host cibuildwheel
- uses: actions/setup-python@v5
- name: Install cibuildwheel
run: python -m pip install cibuildwheel==2.21.2
- name: Build wheels
run: python -m cibuildwheel --output-dir wheelhouse
# to supply options, put them in 'env', like:
# env:
# CIBW_SOME_OPTION: value
- uses: actions/upload-artifact@v4
with:
name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}
path: ./wheelhouse/*.whl
有关更多信息，包括 PyPI 部署和使用其他 CI 服务或专用 GitHub Action，请参阅 文档 和 示例。
它是如何工作的
以下图表总结了 cibuildwheel 在每个平台上执行的步骤。
在文档中探索此图表的交互式版本 在这里。
选项
| 选项 | 描述 | |
|---|---|---|
| 构建选择 | CIBW_PLATFORM |
覆盖自动检测的目标平台 |
CIBW_BUILD CIBW_SKIP |
选择要构建的 Python 版本 | |
CIBW_ARCHS |
更改默认构建在您的机器上的架构。 | |
CIBW_PROJECT_REQUIRES_PYTHON |
手动设置项目的 Python 兼容性 | |
CIBW_PRERELEASE_PYTHONS |
启用使用预发布版本的 Python 构建（如果可用） | |
| 构建自定义 | CIBW_BUILD_FRONTEND |
设置用于构建的工具，可以是 "pip"（默认）或 "build" |
CIBW_ENVIRONMENT |
设置构建过程中需要的环境变量 | |
CIBW_ENVIRONMENT_PASS_LINUX |
在构建过程中将主机上的环境变量传递到容器中 | |
CIBW_BEFORE_ALL |
在构建任何 wheel 之前，在构建系统上执行 shell 命令。 | |
CIBW_BEFORE_BUILD |
执行 shell 命令准备每个 wheel 的构建 | |
CIBW_REPAIR_WHEEL_COMMAND |
执行 shell 命令来修复每个构建的 wheel | |
CIBW_MANYLINUX_*_IMAGECIBW_MUSLLINUX_*_IMAGE |
指定替代的 manylinux / musllinux Docker 镜像 | |
CIBW_CONTAINER_ENGINE |
指定构建 Linux wheel 时使用的容器引擎 | |
CIBW_DEPENDENCY_VERSIONS |
指定 cibuildwheel 如何控制它使用的工具的版本 | |
| 测试 | CIBW_TEST_COMMAND |
执行 shell 命令来测试每个构建的 wheel |
CIBW_BEFORE_TEST |
在测试每个 wheel 之前执行 shell 命令 | |
CIBW_TEST_REQUIRES |
在运行测试之前安装 Python 依赖项 | |
CIBW_TEST_EXTRAS |
使用 extras_require 安装您的 wheel 以进行测试 | |
CIBW_TEST_SKIP |
跳过一些构建的测试运行 | |
| 其他 | CIBW_BUILD_VERBOSITY |
增加/减少 pip wheel 的输出 |
这些选项也可以在 pyproject.toml 文件中指定；请参阅配置。
工作示例
以下是一些使用 cibuildwheel 的仓库。
| 名称 | CI | OS | 备注 |
|---|---|---|---|
| scikit-learn |  |
   |
机器学习库。一个复杂但干净的配置，使用了 cibuildwheel 的许多功能来构建具有 Cython 和 C++ 扩展的大型项目。 |
| pytorch-fairseq | |
|
Facebook AI Research Sequence-to-Sequence Toolkit，用 Python 编写。 |
| NumPy |  |
|
Python 科学计算的基石。 |
| duckdb | |
|
DuckDB 是一个分析型进程内 SQL 数据库管理系统 |
| Tornado | |
|
Tornado 是一个 Python 网络框架和异步网络库。使用稳定的 ABI 来构建一个小型 C 扩展。 |
| NCNN | |
|
ncnn 是一个针对移动平台优化的高性能神经网络推理框架 |
| Matplotlib | |
|
受人尊敬的 Matplotlib，一个具有 C++ 部分的 Python 库 |
| Prophet | |
|
用于生成具有多个季节性和线性或非线性增长的时间序列数据高质量预测的工具 |
| MyPy | |
|
MyPyC 编译的 MyPy 版本 |
| Kivy | |
|
开源 UI 框架，用 Python 编写，支持 Windows、Linux、macOS、Android 和 iOS |
ℹ️ 这只是其中的一小部分，还有更多！请查看文档中的工作示例页面。
法律说明
由于 cibuildwheel 使用 delocate 或 auditwheel 修复 wheel，它可能会自动捆绑构建机器上的动态链接库。
这有助于确保库可以在没有任何 pip 工具链之外的依赖项的情况下运行。
这与静态链接类似，因此可能会有一些许可影响。检查您拉取的任何代码的许可，以确保这是允许的。
更新日志
v2.21.2
2024年10月2日
- ✨ 添加了对 musllinux 上构建 32 位 armv7l wheel 的支持。在设置了仿真的 Linux 系统上，如果您感兴趣，可以将 CIBW_ARCHS 设置为
armv7l以尝试它！ (#2017) - 🐛 修复了一些系统上的 Linux Podman 构建 (#2016)
- ✨ 添加了对 Python 3.13 的官方支持 (#2026)
- 🛠 更新 CPython 3.13 到 3.13.0rc3 (#2029)
注意：默认的manylinux镜像将在2025年5月6日或之后的cibuildwheel版本中从manylinux2014更改为manylinux_2_28 - 如果您想避免升级，现在可以设置该值。（#1992）
v2.21.1
2024年9月16日
- 🐛 修复Linux构建中的错误，其中复制到容器中的文件会有无效的所有权权限（#2007）
- 🐛 修复Windows上的错误，cibuildwheel会调用
uv为它不支持CPython版本的依赖项安装依赖项（#2005） - 🐛 修复在Linux上测试时
uv 0.4.10不会使用正确Python的错误。（#2008） - 🛠 升级我们的文档标记，修复了缺失包的问题（#2011）
v2.21.0
2024年9月13日
- ⚠️ 将CPython 3.12更新到3.12.6，这更改了CPython 3.12在macOS上的最低部署目标，从macOS 10.9更改为macOS 10.13（#1998）
- 🛠 在TOML覆盖中的
config-settings继承时更改行为 - 而不是扩展每个键（这很少有用），将覆盖之前设置的值。 (#1803) - 🛠 将CPython 3.13更新到3.13.0rc2（#1998）
- ✨ 增加对多架构OCI镜像的支持（#1961）
- 🐛 修复在macOS上构建Linux wheels的一些错误（#1961）
- ⚠️ 将Docker/Podman的最低版本更改为Docker API版本1.43，Podman API版本3。这应影响的主要运行者是Travis Graviton2运行者 - 如果是这样，您可以升级您的Docker版本。（#1961）
v2.20.0
2024年8月4日
- 🌟 默认构建CPython 3.13 wheels - 无需
CIBW_PRERELEASE_PYTHONS标志。是时候构建并上传这些wheels到PyPI了！此版本包括CPython 3.13.0rc1，保证与最终版本兼容。多线程仍然在标志/配置选项之后。 (#1950) - ✨ 提供一个
CIBW_ALLOW_EMPTY环境变量，作为命令行标志的替代方案。 (#1937) - 🐛 在Windows上不要使用PyPy3.8上的uv，从0.2.25版本开始它就停止工作了。请注意，PyPy 3.8已达到EoL。 (#1868)
- 🛠 根据目标架构设置
VSCMD_ARG_TGT_ARCH变量。（#1876） - 🛠 现在pytest 8.3已发布，取消清理pytest 8-8.2的输出。（#1943）
- 📚 将示例更新为在主机上使用Python 3.12（从2024年10月开始，cibuildwheel将要求主机机器上安装Python 3.11+）。（#1919）
v2.19.2
2024年7月2日
- 🐛 更新manylinux2014标记，以支持已达到EoL的CentOS 7镜像。（#1917）
- 🐛 支持与
build[uv]构建前端一起使用--no-isolation。（#1889） - 🛠 在https://github.com/pypa/cibuildwheel/attestations上提供发布证明。（#1916）
- 🛠 提供CPython 3.13.0b3。（#1913）
- 🛠 现在pip 21.1可用，移除一些解决方案。（#1891，#1892）
- 📚 从我们的文档中删除nosetest。（#1821）
- 📚 在GHA上为3.8记录macOS ARM的解决方案。（#1871）
- 📚 GitLab CI + macOS现在是一个支持的平台，并附有示例。（#1911）
这是最近几个版本。
ℹ️ 想要更多变更日志？请访问文档中的变更日志页面。
贡献
有关如何为cibuildwheel贡献的更多信息，请参阅文档。
通过代码库、问题跟踪器、聊天室或以其他方式与cibuildwheel项目互动的所有人都应遵循PSF行为准则。
维护者
- Joe Rickerby @joerick
- Yannick Jadoul @YannickJadoul
- Matthieu Darbois @mayeut
- Henry Schreiner @henryiii
- Grzegorz Bokota @Czaki
致谢
cibuildwheel站在巨人的肩膀上。
- ⭐️ @matthew-brett 为 multibuild 和 matthew-brett/delocate
- @PyPA 为许多 Linux Docker 图像 pypa/manylinux
- @ogrisel 为 wheelhouse-uploader 和
run_with_env.cmd
还有许多要感谢的人-
- @zfrenchee 为 帮助调试许多问题
- @lelit 提供了一些出色的错误报告和 贡献
- @mayeut 为一个 惊人的 PR 修复了 Python 本身，以实现更好的兼容性！
- @czaki 作为超级贡献者，在许多 PR 中提供帮助，并解决无数问题！
- @mattip 帮助添加 PyPy 支持到 cibuildwheel
另见
另一个值得考虑的非常相似的工具是 matthew-brett/multibuild。 multibuild 是一个用于在各种平台上构建 wheel 的 shell 脚本工具箱。它被用作构建像 SciPy 这样的大数据科学工具的基础。
如果你正在构建 Rust wheel，你可以在不使用 manylinux 来使 GLIBC 工作的一些技巧的情况下完成，这对于交叉编译尤其相关，而 Rust 的交叉编译非常容易。参见 maturin-action，这是一个针对构建 Rust wheel 和交叉编译进行优化的工具。
下载文件
下载适合您平台的文件。如果您不确定该选择哪个，请了解更多关于安装包的信息。
