Python wheels are great. Building them across Mac, Linux, Windows, on multiple versions of Python, is not.
cibuildwheel is here to help. cibuildwheel runs on your CI server - currently it supports GitHub Actions, Azure Pipelines, Travis CI, CircleCI, and GitLab CI - and it builds and tests your wheels across all of your platforms.
While cibuildwheel itself requires a recent Python version to run (we support the last three releases), it can target the following versions to build wheels:
macOS Intel macOS Apple Silicon Windows 64bit Windows 32bit Windows Arm64 manylinuxยน PyPy & GraalPy are only supported for manylinux wheels.
ยฒ Windows arm64 support is experimental.
ยณ Free-threaded mode requires opt-in on 3.13 using enable.
โด Experimental, not yet supported on PyPI, but can be used directly in web deployment. Use --platform pyodide to build.
โต manylinux armv7l support is experimental. As there are no RHEL based image for this architecture, it's using an Ubuntu based image instead.
See the cibuildwheel 1 documentation if you need to build unsupported versions of Python, such as Python 2.
cibuildwheel runs inside a CI service. Supported platforms depend on which service you're using:
ยน Requires emulation, distributed separately. Other services may also support Linux ARM through emulation or third-party build hosts, but these are not tested in our CI.
ยฒ Uses cross-compilation. It is not possible to test arm64 on this CI platform.
ยณ Requires a macOS runner; runs tests on the simulator for the runner's architecture.
โด Building for Android requires the runner to be Linux x86_64, macOS ARM64 or macOS x86_64. Testing has additional requirements.
To build manylinux, musllinux, macOS, and Windows wheels on GitHub Actions, you could use this .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, ubuntu-24.04-arm, windows-latest, windows-11-arm, macos-13, macos-latest]
steps:
- uses: actions/checkout@v5
# Used to host cibuildwheel
- uses: actions/setup-python@v5
- name: Install cibuildwheel
run: python -m pip install cibuildwheel==3.1.3
- 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
For more information, including PyPI deployment, and the use of other CI services or the dedicated GitHub Action, check out the documentation and the examples.
The following diagram summarises the steps that cibuildwheel takes on each platform.
Explore an interactive version of this diagram in the docs.
Option Description Build selection
platform Override the auto-detected target platform buildskip Choose the Python versions to build archs Change the architectures built on your machine by default. project-requires-python Manually set the Python compatibility of your project enable Enable building with extra categories of selectors present. allow-empty Suppress the error code if no wheels match the specified build identifiers Build customization build-frontend Set the tool to use to build, either "build" (default), "build[uv]", or "pip" config-settings Specify config-settings for the build backend. environment Set environment variables environment-pass Set environment variables on the host to pass-through to the container. before-all Execute a shell command on the build system before any wheels are built. before-build Execute a shell command preparing each wheel's build xbuild-tools Binaries on the path that should be included in an isolated cross-build environment. repair-wheel-command Execute a shell command to repair each built wheel manylinux-*-imagemusllinux-*-image Specify manylinux / musllinux container images container-engine Specify the container engine to use when building Linux wheels dependency-versions Control the versions of the tools cibuildwheel uses pyodide-version Specify the Pyodide version to use for pyodide platform builds Testing test-command The command to test each built wheel before-test Execute a shell command before testing each wheel test-sources Paths that are copied into the working directory of the tests test-requires Install Python dependencies before running the tests test-extras Install your wheel for testing using extras_require test-groups Specify test dependencies from your project's dependency-groups test-skip Skip running tests on some builds test-environment Set environment variables for the test environment Debugging debug-keep-container Keep the container after running for debugging. debug-traceback Print full traceback when errors occur. build-verbosity Increase/decrease the output of the build
These options can be specified in a pyproject.toml file, or as environment variables, see configuration docs.
Here are some repos that use cibuildwheel.
โน๏ธ That's just a handful, there are many more! Check out the Working Examples page in the docs.
Since cibuildwheel repairs the wheel with delocate or auditwheel, it might automatically bundle dynamically linked libraries from the build machine.
It helps ensure that the library can run without any dependencies outside of the pip toolchain.
This is similar to static linking, so it might have some license implications. Check the license for any code you're pulling in to make sure that's allowed.
1 August 2025
29 July 2025
CIBW_FREE_THREADING_SUPPORT is set; you are likely missing 3.13t wheels, please use the enable/CIBW_ENABLE (#2520)riscv64 now enabled if you target that architecture, it's now supported on PyPI (#2509)cpython-experimental-riscv64 (no longer needed) (#2526, #2528)test-skip of "*-macosx_universal2:arm64" (#2522)24 July 2025
23 July 2025
"cpython-prerelease" enable set. It's time to build and upload these wheels to PyPI! This release includes CPython 3.14.0rc1, which is guaranteed to be ABI compatible with the final release. (#2507) Free-threading is no longer experimental in 3.14, so you have to skip it explicitly with 'cp31?t-*' if you don't support it yet. (#2503)platform option to android on Linux or macOS to try it out! (#2349)manylinux_2_28 (now a consistent default) and manylinux_2_34 added (#2500)enable) since you can't push them to PyPI yet (#2506)cp39-musllinux_ricv64 -> cp39-musllinux_riscv64) (#2490)--only now shows the correct possibilities, and even suggests near matches on Python 3.14+ (#2499)5 July 2025
That's the last few versions.
โน๏ธ Want more changelog? Head over to the changelog page in the docs.
For more info on how to contribute to cibuildwheel, see the docs.
Everyone interacting with the cibuildwheel project via codebase, issue tracker, chat rooms, or otherwise is expected to follow the PSF Code of Conduct.
Core:
Platform maintainers:
cibuildwheel stands on the shoulders of giants.
run_with_env.cmdMassive props also to-
Another very similar tool to consider is matthew-brett/multibuild. multibuild is a shell script toolbox for building a wheel on various platforms. It is used as a basis to build some of the big data science tools, like SciPy.
If you are building Rust wheels, you can get by without some of the tricks required to make GLIBC work via manylinux; this is especially relevant for cross-compiling, which is easy with Rust. See maturin-action for a tool that is optimized for building Rust wheels and cross-compiling.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4