Skip to main content

Using cibuildwheel to Create Python Wheels

·2 mins

Have you ever tried to install MySQL-python? It contains the C code and need to compile the code while install the package. You have to follow the steps in this articles: Install MySQL and MySQLClient(Python) in MacOS. Things get worse if you are using Windows.

Luckily, as new distribution format Wheel has been published in PEP 427.

The wheel binary package format frees installers from having to know about the build system, saves time by amortizing compile time over many installations, and removes the need to install a build system in the target environment.

Installation of wheels does not require a compiler on system and is much faster.

Cibuildwheel is a very useful tool for building wheels. It can run on many CI server (GitHub Actions, Travis , Azure Pipelines etc) and build wheels across many platforms.

Usage #

You need to create a configuration file for the CI server, you can read the examples and documents.

For example, GitHub Actions can use this configuration file:

name: Build

on: [push, pull_request]

    name: Build wheels on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
        os: [ubuntu-18.04, windows-latest, macos-latest]

      - uses: actions/checkout@v2

      - uses: actions/setup-python@v2
        name: Install Python
          python-version: '3.7'

      - name: Install cibuildwheel
        run: |
          python -m pip install cibuildwheel==1.5.5          
      - name: Install Visual C++ for Python 2.7
        if: runner.os == 'Windows'
        run: |
          choco install vcpython27 -f -y          
      - name: Build wheels
        run: |
          python -m cibuildwheel --output-dir wheelhouse          
      - uses: actions/upload-artifact@v2
          path: ./wheelhouse/*.whl

Useful Options #

These options can be applied by setting environment variables.


Use this options to filter the Python versions to build.


# Only build on Python 3.6
CIBW_BUILD: cp36-*

# Skip building on Python 2.7 on the Mac
CIBW_SKIP: cp27-macosx_x86_64

# Skip building on Python 3.8 on the Mac
CIBW_SKIP: cp38-macosx_x86_64


Execute the shell command before wheel building.

Upload to PyPI #

Now you can download from Actions panel on GitHub, and unzip it to dist folder. Then manually publish it by rm -rf dist && python sdist && twine upload dist/*. You can get more detailed guide from this article: Packaging Python Projects.

This process can also be done automatically by using CI configuration file. You can find the example configuration files from official repo.

Ref #

  1. Building Python Platform Wheels for Packages with Binary Extensions
  2. How to include external library with python wheel package
  3. cibuildwheel