跳转到主要内容

使用最小配置在 CI 中构建 Python 轮子。

项目描述

cibuildwheel

PyPI Documentation Status Actions Status Travis Status Appveyor status CircleCI Status Azure Status

文档

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 上运行
  • 通过 auditwheeldelocate 在 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_*_IMAGE
CIBW_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 github icon windows icon apple icon linux icon 机器学习库。一个复杂但干净的配置,使用了 cibuildwheel 的许多功能来构建具有 Cython 和 C++ 扩展的大型项目。
pytorch-fairseq github icon apple icon linux icon Facebook AI Research Sequence-to-Sequence Toolkit,用 Python 编写。
NumPy github icon travisci icon windows icon apple icon linux icon Python 科学计算的基石。
duckdb github icon apple icon linux icon windows icon DuckDB 是一个分析型进程内 SQL 数据库管理系统
Tornado github icon linux icon apple icon windows icon Tornado 是一个 Python 网络框架和异步网络库。使用稳定的 ABI 来构建一个小型 C 扩展。
NCNN github icon windows icon apple icon linux icon ncnn 是一个针对移动平台优化的高性能神经网络推理框架
Matplotlib github icon windows icon apple icon linux icon 受人尊敬的 Matplotlib,一个具有 C++ 部分的 Python 库
Prophet github icon windows icon apple icon linux icon 用于生成具有多个季节性和线性或非线性增长的时间序列数据高质量预测的工具
MyPy github icon apple icon linux icon windows icon MyPyC 编译的 MyPy 版本
Kivy github icon windows icon apple icon linux icon 开源 UI 框架,用 Python 编写,支持 Windows、Linux、macOS、Android 和 iOS

ℹ️ 这只是其中的一小部分,还有更多!请查看文档中的工作示例页面。

法律说明

由于 cibuildwheel 使用 delocateauditwheel 修复 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行为准则

维护者

致谢

cibuildwheel站在巨人的肩膀上。

还有许多要感谢的人-

  • @zfrenchee 为 帮助调试许多问题
  • @lelit 提供了一些出色的错误报告和 贡献
  • @mayeut 为一个 惊人的 PR 修复了 Python 本身,以实现更好的兼容性!
  • @czaki 作为超级贡献者,在许多 PR 中提供帮助,并解决无数问题!
  • @mattip 帮助添加 PyPy 支持到 cibuildwheel

另见

另一个值得考虑的非常相似的工具是 matthew-brett/multibuildmultibuild 是一个用于在各种平台上构建 wheel 的 shell 脚本工具箱。它被用作构建像 SciPy 这样的大数据科学工具的基础。

如果你正在构建 Rust wheel,你可以在不使用 manylinux 来使 GLIBC 工作的一些技巧的情况下完成,这对于交叉编译尤其相关,而 Rust 的交叉编译非常容易。参见 maturin-action,这是一个针对构建 Rust wheel 和交叉编译进行优化的工具。

项目详情


发布历史 发布通知 | RSS 源

下载文件

下载适合您平台的文件。如果您不确定该选择哪个,请了解更多关于安装包的信息。

源分布

cibuildwheel-2.21.2.tar.gz (289.8 kB 查看哈希值)

上传时间

构建分布

cibuildwheel-2.21.2-py3-none-any.whl (89.7 kB 查看哈希值)

上传时间 Python 3

由以下支持

AWSAWS云计算和安全赞助商DatadogDatadog监控FastlyFastlyCDNGoogleGoogle下载分析MicrosoftMicrosoftPSF赞助商PingdomPingdom监控SentrySentry错误记录StatusPageStatusPage状态页面