cibuildwheel

Documentation

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:

^{1 PyPy & GraalPy are only supported for manylinux wheels.
2 Windows arm64 support is experimental.
3 Not supported on PyPI, uses old pyodide tag instead of pyemscripten. Requires pyodide-eol enable.
4 manylinux armv7l support is experimental. As there are no RHEL based image for this architecture, it's using an Ubuntu based image instead.}

• Builds manylinux, musllinux, macOS, Windows, pyemscripten, iOS, and Android wheels
• Supports CPython, PyPy, and GraalPy
• Works on GitHub Actions, Azure Pipelines, CircleCI, and GitLab CI
• Bundles shared library dependencies on Linux through auditwheel, macOS through delocate, and Windows through delvewheel
• 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:

^{1 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.
2 Uses cross-compilation. It is not possible to test arm64 on this CI platform.
3 Requires a macOS runner; runs tests on the simulator for the runner's architecture.
4 Building for Android requires the runner to be Linux x86_64, macOS ARM64 or macOS x86_64. Testing has additional requirements.
5 Builds may work, but are untested in cibuildwheel's CI.}

Example setup

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-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==4.2.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

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.

These options can be specified in a pyproject.toml file, or as environment variables, see configuration docs.

Working examples

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.

Legal note

Since cibuildwheel repairs the wheel with delocate, auditwheel, or delvewheel, 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.

Changelog

v4.2.0

4 August 2026

• 🌟 CPython 3.15 wheels are now built by default - without the "cpython-prerelease" enable set. It's time to build and upload these wheels to PyPI! This release includes CPython 3.15.0rc1, which is guaranteed to be ABI compatible with the final release. (#2944)
• ✨ Adds Pyodide 3.15 support with the cp315-pyodide_wasm32 build identifier, using Pyodide 315.0.0a2. These are also stable wrt. the final release. (#2958)
• 🐛 Retries a failed download six times with exponential backoff, so short network outages no longer stop a build. A 4xx response is still reported at once. (#2953)
• 🐛 Accepts default as a build-frontend value on Pyodide, and accepts pyodide-build in the top-level table and in overrides (#2951)
• 🛠 Holds pip back on GraalPy, where newer pip breaks the build (#2955)
• 🛠 Updates Pyodide to 314.0.4 (#2949, #2952)
• 🛠 Updates dependencies and container pins (#2952, #2960)
• 💼 Updates CI action pins (#2948, #2954)
• 🧪 Uses pp311 for the abi3 test, and deletes test_overridden_pip_constraint, which is not necessary since #2583 (#2956, #2957)

v4.1.1

24 July 2026

• ✨ Adds pyodide-build as a separate build-frontend, now the default frontend for Pyodide, with verbosity flags handling. Any other frontend is ignored with a warning on Pyodide. (#2609, #2945)
• 🔐 Uses digests instead of tags for pinned container images, strengthening supply-chain security. The human-readable tags remain as comments in pinned_docker_images.cfg. (#2915)
• 🐛 Fixes platform-specific test-runtime environment variables (e.g. CIBW_TEST_RUNTIME_ANDROID) not being honored (#2941)
• 🐛 Fixes quoting of test-requires and audit-requires so PEP 508 specifiers containing spaces work (#2913)
• 🐛 Makes archs parsing case-insensitive and platform-aware, so e.g. arm64 works on Windows (#2920)
• 🐛 Uses an absolute path for the {project} placeholder in config-settings (#2934)
• 🐛 Validates the pyodide-version option against the build identifier with a clear error (#2925)
• 🐛 Fixes PyPy installs on macOS after PyPy switched its downloads from .tar.bz2 to .tar.gz (#2939)
• 🐛 Makes a matching python3-config available in the build and test venvs on macOS (#2922)
• 🛠 Updates dependencies and container pins (#2917, #2935, #2939)
• 🛠 Updates Android tests to current Python versions and the new test repository URL (#2933)
• 🛠 Drops the orjson dependency, no longer used by mypy 2+ (#2923)
• 📚 Builds the docs with properdocs, a MkDocs fork (#2946)
• 📚 Adds the missing cp314-pyodide_wasm32 entry to the build identifier table (#2947)
• 📚 Removes outdated notes about the pip wheel build frontend and ClearLinux (#2926)
• 💼 Adds a "CI: PyPy EoL" PR label to run PyPy EoL tests on PRs (#2930)
• 💼 Updates CI action pins and pre-commit hooks (#2914, #2932, #2938, #2940, #2942, #2943)

v4.1.0

12 June 2026

• ✨ Updates Pyodide to the final 314.0.0 release, so Pyodide 3.14 wheels now build by default without the pyodide-prerelease enable flag. (#2906)
• 🐛 Raises clear errors when a build produces no wheel, instead of failing later with a confusing message (#2909)
• 🛠 Speeds up CLI startup through lazy imports on Python 3.15 (#2797)
• 📚 Adds an FAQ section on caching cibuildwheel's downloaded tools with CIBW_CACHE_PATH (#2842)
• 📚 Documentation improvements: clarifies which shell is used for command options, clarifies environment variable precedence, and fixes a dead Pyodide env info link (#2904, #2905, #2911)

v4.0.0

7 June 2026

See @henryiii's release post for more info on new features!

• 🌟 Adds wheel auditing with abi3audit as a default after the repair step, with new audit-requires and audit-command options (#2805)

• 🌟 Adds pyemscripten platform tag support (PEP 783), updates Pyodide to 314.0.0a2, and adds a pyodide-eol enable flag for building end-of-life Pyodide versions (#2812, #2848)

• 🌟 Sets up delvewheel as the default repair-wheel-command for Windows, so extension module DLLs are now bundled automatically. Skip by setting it to empty if not needed. (#2831)

• ✨ Adds CPython 3.15 support, under the enable option cpython-prerelease. This version of cibuildwheel uses 3.15.0b2. (#2833, #2850)

  While CPython is in beta, the ABI can change, so your wheels might not be compatible with the final release. For this reason, we don't recommend distributing wheels until RC1, at which point 3.15 will be available in cibuildwheel without the flag.

• ✨ Adds CPython 3.15 support for iOS and Android (#2857, #2858)

• ✨ Adds Android improvements for building NumPy and related packages, including auditwheel support, pkg-config and Fortran configuration, and the xbuild-files option (#2695)

• ✨ Adds CIBUILDWHEEL_BUILD_IDENTIFIER environment variable set to the current build identifier (e.g. cp311-manylinux_x86_64) during per-build steps (#2872)

• ✨ Adds {project} and {package} placeholders to config-settings (#2827)

• ⚠️ Drops support for Python 3.8 (#2686)

• ⚠️ Removes the experimental CPython 3.13 free-threading builds and the cpython-freethreading enable option. CPython 3.14+ free-threading support remains available without the enable flag. (#2684)

• ⚠️ Drops support for Cirrus CI, which is shutting down June 1, 2026 (#2817)

• ⚠️ Drops GraalPy 3.11 (gp311) support, as agreed in #2741, and removes GraalPy 24-only workarounds (#2895)

• 🔐 Adds SHA256 verification for direct downloads of Python interpreters, virtualenv, and python-build-standalone assets (#2873)

• 🔐 Adds tarfile extraction filter for safe archive extraction (#2856)

• 🐛 Fixes UV_PYTHON not being set for before-build on Linux when using uv as the build-frontend (#2830)

• 🐛 Fixes detection of musl libc when downloading python-build-standalone, which previously always selected the gnu asset on musl hosts like Alpine (#2889)

• 🐛 Fixes config-settings expansion when {project} or {package} contains spaces or backslashes (#2886)

• 🐛 Prevents deadlock when linux32 fails and forwards platform args to the sanity check (#2880, #2888)

• 🐛 Fixes container resource leaks on start failure and during teardown (#2879, #2887)

• 🐛 Removes potential partial cache-population in case of error (#2892)

• 🐛 Raises a clear error when ANDROID_API_LEVEL is not an integer (#2891)

• 🐛 Replaces assert with proper exception in python-build-standalone (#2859)

• 🐛 Uses ConfigurationError when package_dir is outside cwd instead of a generic Exception (#2898)

• 🛠 Updates dependencies and container pins (#2893, #2882, #2874, #2868, #2862, #2884, #2845, #2837, #2818, #2810, #2838, #2813)

• 🛠 Updates Android to Python 3.13.13 and 3.14.4 (#2821)

• 🛠 Applies Pyodide-specific patches to the Emscripten toolchain installation (#2800)

• 🛠 Uses python -V -V for Windows build diagnostics (#2832)

• 🛠 Simplifies pinned container image lookup (#2897)

• 🛠 Minor fixups across error messages, OCI container, and options (#2860)

• 💼 Adds PEP 723 metadata for bin/ scripts and drops the bin dependency group (#2819)

• 💼 Improves Azure test reliability with retries and caching (#2890)

• 💼 Fixes Windows GitLab CI test running (#2870)

• 💼 Updates CI action pins and dev dependencies (#2902, #2867, #2851, #2843, #2826, #2823, #2820, #2807)

• 💼 Adds agent and copilot setup files (#2861)

• 💼 Uses if TYPE_CHECKING: blocks (#2866, #2864)

• 🧪 Fixes Android tests using the uv frontend (#2809)

• 🧪 Fixes the update-dependencies workflow to use uv to run nox (#2808)

• 🧪 Adds unit tests for OCIContainer._get_platform_args (#2878)

• 📚 Updates documentation for delvewheel as the default Windows repair-wheel-command, including the build diagram, schema defaults, and legal note (#2877, #2853, #2891)

• 📚 Documents platform-specific before-build configuration (#2834)

• 📚 Updates the "How it works" diagram with details of Android, iOS, and Pyodide builds (#2816)

• 📚 Adds Pyodide icon and regenerates working examples data for Android, iOS, and Pyodide (#2815, #2811)

• 📚 Adds intersphinx support for external documentation linking (#2871)

• 📚 Adds instructions for building CUDA wheels and fixes manylinux container references in FAQ (#2896, #2900)

• 📚 Links back to source in docs (#2806)

• 📚 Removes outdated numpy info (#2855)

v3.4.1

2 April 2026

• ⚠️ Building for the experimental CPython 3.13 free-threading variant is now deprecated. That functionality will be removed in the next minor release. The enable option cpython-freethreading is therefore also deprecated. Builds specifying enable = "all" no longer select cpython-freethreading. CPython 3.14 free-threading support remains available without the enable flag. (#2787)
• 🐛 iOS builds will no longer skip repair-wheel-command if it's defined in config (#2761)
• 🐛 Fix bug causing uv to fail when environments define PYTHON_VERSION or UV_PYTHON, conflicting with our venvs (#2795)
• ✨ cibuildwheel prints the selected build identifiers at the start of the build. (#2785)
• 🔐 The GitHub Action now references other actions with a full SHA (#2744)

---

That's the last few versions.

ℹ️ Want more changelog? Head over to the changelog page in the docs.

---

Contributing

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.

Maintainers

Core:

• Joe Rickerby @joerick
• Yannick Jadoul @YannickJadoul
• Matthieu Darbois @mayeut
• Henry Schreiner @henryiii
• Grzegorz Bokota @Czaki
• Agriya Khetarpal @agriyakhetarpal (also Pyodide)

Platform maintainers:

• Russell Keith-Magee @freakboy3742 (iOS)
• Hood Chatham @hoodmane (Pyodide)
• Gyeongjae Choi @ryanking13 (Pyodide)
• Tim Felgentreff @timfel (GraalPy)
• Malcolm Smith @mhsmith (Android)

Credits

cibuildwheel stands on the shoulders of giants.

• ⭐️ @matthew-brett for multibuild and matthew-brett/delocate
• @PyPA for the manylinux Docker images pypa/manylinux
• @ogrisel for wheelhouse-uploader and run_with_env.cmd

Massive props also to-

• @zfrenchee for help debugging many issues
• @lelit for some great bug reports and contributions
• @mayeut for a phenomenal PR patching Python itself for better compatibility!
• @czaki for being a super-contributor over many PRs and helping out with countless issues!
• @mattip for his help with adding PyPy support to cibuildwheel

See also

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.