Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
This GitHub Actions workflow demonstrates how to build cross-platform Python wheels using cibuildwheel. It checks out the repository, sets up Python, installs cibuildwheel, builds wheels for various operating systems and architectures, and then uploads the generated wheel files as artifacts.
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.1
- 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
cibuildwheel --version
Debug
Known issues
deprecatedBuilding for the experimental CPython 3.13 free-threading variant is now deprecated and will be removed in the next minor release. The `enable` option `cpython-freethreading` is also deprecated.fixCPython 3.14 free-threading support remains available without the `enable` flag. Avoid explicitly enabling `cpython-freethreading` for 3.13 builds.
affects: 3.4.1 onwards
deprecatedcibuildwheel no longer officially supports running on Travis CI. While it may continue to function, it is no longer tested by the project.fixMigrate your CI workflows to a currently supported service such as GitHub Actions, Azure Pipelines, CircleCI, or GitLab CI.
affects: 3.4.0 onwards
deprecatedPyPy 3.10 has reached end-of-life (EOL) and has been moved to the `pypy-eol` group within the `enable` option.fixIf you need to target PyPy 3.10, you must explicitly enable `pypy-eol`. It is recommended to upgrade to a supported PyPy version if possible.
affects: 3.2.0 onwards
breakingSetting the `CIBW_FREE_THREADING_SUPPORT` environment variable will now raise an error. This variable is deprecated and likely indicates that 3.13t wheels are missing.fixUse the `enable` or `CIBW_ENABLE` option to manage free-threading builds instead.
affects: 3.1.2 onwards
gotchaOlder versions of cibuildwheel (prior to 3.3.0) had known incompatibilities with Docker v29.fixUpgrade cibuildwheel to version 3.3.0 or newer to ensure compatibility with Docker v29.
affects: Prior to 3.3.0
gotchacibuildwheel is designed for isolated CI environments and is not recommended for running on a local development machine, especially for macOS and Windows. It may install Python packages globally to system locations.fixAlways use cibuildwheel within a dedicated CI service (e.g., GitHub Actions) or, for local Linux testing, within a Docker container.
affects: All versions
gotchaWhen building macOS wheels with native library dependencies (e.g., installed via Homebrew), a common issue is that the libraries are compiled for the build machine's macOS version. This can lead to wheels that are not compatible with older macOS versions, as `MACOSX_DEPLOYMENT_TARGET` might be incorrectly set or ignored by external package managers.fixAvoid using package managers like Homebrew for native library dependencies on macOS when building wheels. Instead, compile the required libraries yourself within the `before-all` step of cibuildwheel, which correctly sets the `MACOSX_DEPLOYMENT_TARGET` environment variable.
affects: All versions, when using system package managers for native dependencies on macOS.
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: 'cibuildwheel'
The `cibuildwheel` command or executable is not found in the system's PATH, meaning it's either not installed or its installation directory is not accessible.
fixEnsure `cibuildwheel` is installed (e.g., `pip install cibuildwheel`) and that your system's PATH includes the directory where the executable resides.
fatal error: <header_file>.h: No such file or directory
The C/C++ compiler cannot find a required header file (e.g., from NumPy, OpenMP, or another C extension dependency) during the build of your Python package's compiled components.
fixInstall the necessary development headers for the dependency (e.g., `numpy-dev` on Linux, a C compiler toolchain, or specific libraries like `libomp-dev`) and ensure include paths are correctly configured, potentially via `CIBW_ENVIRONMENT`.
Command '['pip', 'install', ...]' failed with code 1.
An internal `pip install` command executed by `cibuildwheel` (often for build dependencies or during wheel repair) failed, possibly due to network issues, incompatible package versions, or compilation errors within a dependency.
fixExamine the full build log preceding this error for the specific reason `pip` failed. Common solutions include checking network connectivity, resolving dependency conflicts in `pyproject.toml` or `setup.py`, or ensuring build requirements are met for sub-dependencies.
cibuildwheel: error: Build failed because a wheel named <wheel_name>.whl was already generated in the current run.
`cibuildwheel` detected that a wheel with the same name was generated more than once for a single build target, usually indicating a misconfiguration in the project's build backend or custom build commands that produce redundant wheels.
fixReview your `pyproject.toml`, `setup.py`, and any `CIBW_BEFORE_BUILD` or `CIBW_BUILD_COMMAND` settings to ensure that the build process for each wheel variant (e.g., `cp39-manylinux_x86_64`) produces only one final wheel file. Increase `CIBW_BUILD_VERBOSITY=1` for more detailed logs.
Python version not found: <version_string>
`cibuildwheel` was configured to build for a specific Python version (e.g., via `CIBW_BUILD` or by default targets) that is not installed or available in the Continuous Integration (CI) environment where it is running.
fixAdjust the `CIBW_BUILD` or `CIBW_SKIP` environment variables in your CI configuration to match the Python versions actually available on the CI runner, or ensure the required Python versions are installed in the CI environment.
Upgrade
Version history
3.4.1latest on PyPI · released Apr 2, 2026
Audit
Dependencies
DockerrequiredRequired for building Linux wheels in manylinux/musllinux containers.
PodmanoptionalAlternative to Docker for building Linux wheels.
Xcode Command Line ToolsrequiredRequired for building macOS wheels.
Microsoft Visual C++ (MSVC)requiredRequired for building Windows wheels.
Android SDKoptionalRequired for building Android wheels.