{"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":"en","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,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}