cibuildwheel

Warnings

• deprecated 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.
  Fix: CPython 3.14 free-threading support remains available without the `enable` flag. Avoid explicitly enabling `cpython-freethreading` for 3.13 builds.
• deprecated cibuildwheel no longer officially supports running on Travis CI. While it may continue to function, it is no longer tested by the project.
  Fix: Migrate your CI workflows to a currently supported service such as GitHub Actions, Azure Pipelines, CircleCI, or GitLab CI.
• deprecated PyPy 3.10 has reached end-of-life (EOL) and has been moved to the `pypy-eol` group within the `enable` option.
  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.
• breaking 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.
  Fix: Use the `enable` or `CIBW_ENABLE` option to manage free-threading builds instead.
• gotcha Older versions of cibuildwheel (prior to 3.3.0) had known incompatibilities with Docker v29.
  Fix: Upgrade cibuildwheel to version 3.3.0 or newer to ensure compatibility with Docker v29.
• gotcha 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.
  Fix: Always use cibuildwheel within a dedicated CI service (e.g., GitHub Actions) or, for local Linux testing, within a Docker container.
• gotcha 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.
  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.

Install

• pip install cibuildwheel Install latest version

Quickstart

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