How to Build Python Wheels for Many Platforms With cibuildwheel

pypa/cibuildwheel builds wheels for every CPython version and platform in an os matrix, using manylinux containers on Linux and native toolchains on macOS and Windows.

Compiled Python packages need a wheel per platform and interpreter. cibuildwheel orchestrates all of that: run it in an os matrix and it emits the full set.

Steps

• Add an os matrix over the three runner labels.
• Run pypa/cibuildwheel to build wheels for each Python version.
• Upload the wheelhouse/ directory as an artifact per OS.

Workflow

jobs:
  wheels:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: pypa/cibuildwheel@v2.19
        env:
          CIBW_BUILD: 'cp39-* cp310-* cp311-* cp312-*'
      - uses: actions/upload-artifact@v4
        with:
          name: wheels-${{ matrix.os }}
          path: wheelhouse/*.whl

Gotchas

• Linux wheels build inside manylinux containers, so system libraries must be installed with CIBW_BEFORE_ALL, not on the host.
• For arm64 Linux wheels, cibuildwheel uses emulation unless you run on a native arm runner.

Related guides