{"id":4472,"library":"cibuildwheel","title":"cibuildwheel","description":"cibuildwheel simplifies the creation of Python wheels for various platforms and Python versions within Continuous Integration (CI) workflows. It builds manylinux, musllinux, macOS, and Windows wheels for CPython, PyPy, and GraalPy across multiple architectures. The library is actively maintained with frequent minor and patch releases, ensuring compatibility with the latest Python versions and CI environments.","status":"active","version":"3.4.1","language":"python","source_language":"en","source_url":"https://github.com/pypa/cibuildwheel","tags":["ci","build","wheels","cross-platform","packaging"],"install":[{"cmd":"pip install cibuildwheel","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for building Linux wheels in manylinux/musllinux containers.","package":"Docker","optional":false},{"reason":"Alternative to Docker for building Linux wheels.","package":"Podman","optional":true},{"reason":"Required for building macOS wheels.","package":"Xcode Command Line Tools","optional":false},{"reason":"Required for building Windows wheels.","package":"Microsoft Visual C++ (MSVC)","optional":false},{"reason":"Required for building Android wheels.","package":"Android SDK","optional":true}],"imports":[],"quickstart":{"code":"name: Build\non:\n  [push, pull_request]\n\njobs:\n  build_wheels:\n    name: Build wheels on ${{ matrix.os }}\n    runs-on: ${{ matrix.os }}\n    strategy:\n      matrix:\n        os: [ubuntu-latest, ubuntu-24.04-arm, windows-latest, windows-11-arm, macos-15-intel, macos-latest]\n\n    steps:\n      - uses: actions/checkout@v6\n        with:\n          persist-credentials: false\n\n      # Used to host cibuildwheel\n      - uses: actions/setup-python@v6\n\n      - name: Install cibuildwheel\n        run: python -m pip install cibuildwheel==3.4.1\n\n      - name: Build wheels\n        run: python -m cibuildwheel --output-dir wheelhouse\n        # to supply options, put them in 'env', like:\n        # env:\n        #   CIBW_SOME_OPTION: value\n\n      - uses: actions/upload-artifact@v4\n        with:\n          name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}\n          path: ./wheelhouse/*.whl","lang":"yaml","description":"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."},"warnings":[{"fix":"CPython 3.14 free-threading support remains available without the `enable` flag. Avoid explicitly enabling `cpython-freethreading` for 3.13 builds.","message":"Building 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.","severity":"deprecated","affected_versions":"3.4.1 onwards"},{"fix":"Migrate your CI workflows to a currently supported service such as GitHub Actions, Azure Pipelines, CircleCI, or GitLab CI.","message":"cibuildwheel no longer officially supports running on Travis CI. While it may continue to function, it is no longer tested by the project.","severity":"deprecated","affected_versions":"3.4.0 onwards"},{"fix":"If 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.","message":"PyPy 3.10 has reached end-of-life (EOL) and has been moved to the `pypy-eol` group within the `enable` option.","severity":"deprecated","affected_versions":"3.2.0 onwards"},{"fix":"Use the `enable` or `CIBW_ENABLE` option to manage free-threading builds instead.","message":"Setting 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.","severity":"breaking","affected_versions":"3.1.2 onwards"},{"fix":"Upgrade cibuildwheel to version 3.3.0 or newer to ensure compatibility with Docker v29.","message":"Older versions of cibuildwheel (prior to 3.3.0) had known incompatibilities with Docker v29.","severity":"gotcha","affected_versions":"Prior to 3.3.0"},{"fix":"Always use cibuildwheel within a dedicated CI service (e.g., GitHub Actions) or, for local Linux testing, within a Docker container.","message":"cibuildwheel 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid 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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions, when using system package managers for native dependencies on macOS."}],"env_vars":null,"search_vec":"'across':33 'activ':39 'architectur':35 'build':21,58 'ci':18,55,57 'cibuildwheel':1,2 'compat':48 'continu':16 'cpython':29 'creation':5 'cross':61 'cross-platform':60 'ensur':47 'environ':56 'frequent':42 'graalpi':32 'integr':17 'latest':51 'librari':37 'maco':24 'maintain':40 'manylinux':22 'minor':43 'multipl':34 'musllinux':23 'packag':63 'patch':45 'platform':11,62 'pypi':30 'python':7,13,52 'releas':46 'simplifi':3 'various':10 'version':14,53 'wheel':8,27,59 'window':26 'within':15 'workflow':19","created_at":"2026-04-12T13:54:07.325333+00:00","updated_at":"2026-04-16T02:08:49.189956+00:00","problems":[{"fix":"Ensure `cibuildwheel` is installed (e.g., `pip install cibuildwheel`) and that your system's PATH includes the directory where the executable resides.","cause":"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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'cibuildwheel'"},{"fix":"Install 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`.","cause":"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.","error":"fatal error: <header_file>.h: No such file or directory"},{"fix":"Examine 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.","cause":"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.","error":"Command '['pip', 'install', ...]' failed with code 1."},{"fix":"Review 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.","cause":"`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.","error":"cibuildwheel: error: Build failed because a wheel named <wheel_name>.whl was already generated in the current run."},{"fix":"Adjust 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.","cause":"`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.","error":"Python version not found: <version_string>"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"cibuildwheel","cli_version":"usage: cibuildwheel [-h]","type":"library","homepage":null,"github":"https://github.com/pypa/cibuildwheel#changelog","docs":"https://cibuildwheel.pypa.io","changelog":"https://github.com/pypa/cibuildwheel#changelog","pypi":"https://pypi.org/project/cibuildwheel/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-12","next_check":"2026-07-11","install_tag":null}}