cibuildwheel

Documentation

<!--intro-start-->

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, CircleCI, and GitLab CI - and it builds and tests your wheels across all of your platforms.

What does it do?

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<br/>musllinux x86_64 | manylinux<br/>musllinux i686 | manylinux<br/>musllinux aarch64 | manylinux<br/>musllinux ppc64le | manylinux<br/>musllinux s390x | manylinux<br/>musllinux armv7l | Android | iOS | Pyodide | |--------------------|----|-----|----|-----|-----|----|-----|----|-----|-----|---|-----|-----|-----| | CPython 3.8 | ✅ | ✅ | ✅ | ✅ | N/A | ✅ | ✅ | ✅ | ✅ | ✅ | ✅⁵ | N/A | N/A | N/A | | CPython 3.9 | ✅ | ✅ | ✅ | ✅ | ✅² | ✅ | ✅ | ✅ | ✅ | ✅ | ✅⁵ | N/A | N/A | N/A | | CPython 3.10 | ✅ | ✅ | ✅ | ✅ | ✅² | ✅ | ✅ | ✅ | ✅ | ✅ | ✅⁵ | N/A | N/A | N/A | | CPython 3.11 | ✅ | ✅ | ✅ | ✅ | ✅² | ✅ | ✅ | ✅ | ✅ | ✅ | ✅⁵ | N/A | N/A | N/A | | CPython 3.12 | ✅ | ✅ | ✅ | ✅ | ✅² | ✅ | ✅ | ✅ | ✅ | ✅ | ✅⁵ | N/A | N/A | ✅⁴ | | CPython 3.13³ | ✅ | ✅ | ✅ | ✅ | ✅² | ✅ | ✅ | ✅ | ✅ | ✅ | ✅⁵ | ✅ | ✅ | ✅⁴ | | CPython 3.14 | ✅ | ✅ | ✅ | ✅ | ✅² | ✅ | ✅ | ✅ | ✅ | ✅ | ✅⁵ | ✅ | ✅ | N/A | | PyPy 3.8 v7.3 | ✅ | ✅ | ✅ | N/A | N/A | ✅¹ | ✅¹ | ✅¹ | 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 | N/A | N/A | | PyPy 3.10 v7.3 | ✅ | ✅ | ✅ | N/A | N/A | ✅¹ | ✅¹ | ✅¹ | N/A | N/A | N/A | N/A | N/A | N/A | | PyPy 3.11 v7.3 | ✅ | ✅ | ✅ | N/A | N/A | ✅¹ | ✅¹ | ✅¹ | N/A | N/A | N/A | N/A | N/A | N/A | | GraalPy 3.11 v24.2 | ✅ | ✅ | ✅ | N/A | N/A | ✅¹ | N/A | ✅¹ | N/A | N/A | N/A | N/A | N/A | N/A | | GraalPy 3.12 v25.0 | ✅ | ✅ | ✅ | N/A | N/A | ✅¹ | N/A | ✅¹ | N/A | N/A | N/A | N/A | N/A | N/A |

^{¹ PyPy & GraalPy are only supported for manylinux wheels.}<br> ^{² Windows arm64 support is experimental.}<br> ^{³ Free-threaded mode requires opt-in on 3.13 using enable.}<br> ^{⁴ Experimental, not yet supported on PyPI, but can be used directly in web deployment. Use --platform pyodide to build.}<br> ^{⁵ manylinux armv7l support is experimental. As there are no RHEL based image for this architecture, it's using an Ubuntu based image instead.}<br>

• Builds manylinux, musllinux, macOS, and Windows wheels for CPython, PyPy, and GraalPy
• Works on GitHub Actions, Azure Pipelines, CircleCI, GitLab CI, and Cirrus CI
• Bundles shared library dependencies on Linux and macOS through auditwheel and delocate
• Runs your library's tests against the wheel-installed version of your library

See the cibuildwheel 1 documentation if you need to build unsupported versions of Python, such as Python 2.

Usage

cibuildwheel runs inside a CI service. Supported platforms depend on which service you're using:

| | Linux | macOS | Windows | Linux ARM | macOS ARM | Windows ARM | Android | iOS | |-----------------|-------|-------|---------|-----------|-----------|-------------|---------|-----| | GitHub Actions | ✅ | ✅ | ✅ | ✅ | ✅ | ✅² | ✅⁴ | ✅³ | | Azure Pipelines | ✅ | ✅ | ✅ | | ✅ | ✅² | ✅⁴ | ✅³ | | CircleCI | ✅ | ✅ | | ✅ | ✅ | | ✅⁴ | ✅³ | | Gitlab CI | ✅ | ✅ | ✅ | ✅¹ | ✅ | | ✅⁴ | ✅³ | | Cirrus CI | ✅ | ✅ | ✅ | ✅ | ✅ | | ✅⁴ | |

^{¹ 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.}<br> ^{² Uses cross-compilation. It is not possible to test arm64 on this CI platform.}<br> ^{³ Requires a macOS runner; runs tests on the simulator for the runner's architecture.}<br> ^{⁴ Building for Android requires the runner to be Linux x86_64, macOS ARM64 or macOS x86_64. Testing has additional requirements.}<br>

<!--intro-end-->

Example setup

To build manylinux, musllinux, macOS, and Windows wheels on GitHub Actions, you could use this .github/workflows/wheels.yml:

<!--generic-github-start-->

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-15-intel, macos-latest]

    steps:
      - uses: actions/checkout@v6
        with:
          persist-credentials: false

      # Used to host cibuildwheel
      - uses: actions/setup-python@v6

      - name: Install cibuildwheel
        run: python -m pip install cibuildwheel==3.4.0

      - 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@v6
        with:
          name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}
          path: ./wheelhouse/*.whl

<!--generic-github-end-->

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.

How it works

The following diagram summarises the steps that cibuildwheel takes on each platform.

^{Explore an interactive version of this diagram in the docs.}

[!WARNING] Building and testing wheels executes arbitrary code from your project and its dependencies. Although cibuildwheel uses OCI containers and Pyodide for some builds, these provide no security guarantees - the code you're building and testing has full access to the environment that's invoking cibuildwheel.

If you cannot trust all the code that's pulled in, maintain good security hygiene: keep the job that builds distributions separate from the job that uploads them to PyPI, handle secrets and credentials with care and rotate them regularly, and follow the principle of least privilege when granting permissions. Do not store sensitive data on CI runners.

<!--[[[cog from readme_options_table import get_table; print(get_table()) ]]]--> <!-- This table is auto-generated from docs/options.md by bin/readme_options_table.py -->

| | Option | Description | |---|---|---| | Build selection | platform | Override the auto-detected target platform | | | build<br>skip | 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 buil