Options summary

Setting options

cibuildwheel is configured using environment variables, that can be set using your CI config.

For example, to configure cibuildwheel to run tests, add the following YAML to your CI config file:

.travis.yml (docs)

env:
  global:
    - CIBW_TEST_REQUIRES=pytest
    - CIBW_TEST_COMMAND="pytest {project}/tests"

appveyor.yml (docs)

environment:
  global:
    CIBW_TEST_REQUIRES: pytest
    CIBW_TEST_COMMAND: "pytest {project}\\tests"

.circleci/config.yml (docs)

jobs:
  job_name:
    environment:
      CIBW_TEST_REQUIRES: pytest
      CIBW_TEST_COMMAND: "pytest {project}/tests"

azure-pipelines.yml (docs)

variables:
  CIBW_TEST_REQUIRES: pytest
  CIBW_TEST_COMMAND: "pytest {project}/tests"

.github/workflows/*.yml (docs) (can be global, in job, or in step)

env:
  CIBW_TEST_REQUIRES: pytest
  CIBW_TEST_COMMAND: "pytest {project}/tests"

Build selection

CIBW_PLATFORM

Override the auto-detected target platform

Options: auto linux macos windows

Default: auto

auto will auto-detect platform using environment variables, such as TRAVIS_OS_NAME/APPVEYOR/CIRCLECI.

For linux you need Docker running, on macOS or Linux. For macos, you need a Mac machine, and note that this script is going to automatically install MacPython on your system, so don't run on your development machine. For windows, you need to run in Windows, and cibuildwheel will install required versions of Python to C:\cibw\python using NuGet.

This option can also be set using the command-line option --platform.

CIBW_BUILD, CIBW_SKIP

Choose the Python versions to build

Space-separated list of builds to build and skip. Each build has an identifier like cp27-manylinux_x86_64 or cp35-macosx_x86_64 - you can list specific ones to build and cibuildwheel will only build those, and/or list ones to skip and cibuildwheel won't try to build them.

When both options are specified, both conditions are applied and only builds with a tag that matches CIBW_BUILD and does not match CIBW_SKIP will be built.

When setting the options, you can use shell-style globbing syntax (as per fnmatch). All the build identifiers supported by cibuildwheel are shown below:

macOS 64bit Manylinux x86 64bit Manylinux x86 32bit Windows 64bit Windows 32bit Manylinux Armv8 64bit Manylinux PPC64LE Manylinux s390x
Python 2.7 cp27-macosx_x86_64 cp27-manylinux_x86_64 cp27-manylinux_i686 cp27-win_amd64 cp27-win32
Python 3.5 cp35-macosx_x86_64 cp35-manylinux_x86_64 cp35-manylinux_i686 cp35-win_amd64 cp35-win32 cp35-manylinux_aarch64 cp35-manylinux_ppc64le cp35-manylinux_s390x
Python 3.6 cp36-macosx_x86_64 cp36-manylinux_x86_64 cp36-manylinux_i686 cp36-win_amd64 cp36-win32 cp36-manylinux_aarch64 cp36-manylinux_ppc64le cp36-manylinux_s390x
Python 3.7 cp37-macosx_x86_64 cp37-manylinux_x86_64 cp37-manylinux_i686 cp37-win_amd64 cp37-win32 cp37-manylinux_aarch64 cp37-manylinux_ppc64le cp37-manylinux_s390x
Python 3.8 cp38-macosx_x86_64 cp38-manylinux_x86_64 cp38-manylinux_i686 cp38-win_amd64 cp38-win32 cp38-manylinux_aarch64 cp38-manylinux_ppc64le cp38-manylinux_s390x
PyPy 2.7 v7.3.0 pp27-macosx_x86_64 pp27-manylinux_x86_64 pp27-win32
PyPy 3.6 v7.3.0 pp36-macosx_x86_64 pp36-manylinux_x86_64 pp36-win32

The list of supported and currently selected build identifiers can also be retrieved by passing the --print-build-identifiers flag to cibuildwheel. The format is python_tag-platform_tag, with tags similar to those in PEP 425.

For CPython, the minimally supported macOS version is 10.9; for PyPy 2.7 and PyPy 3.6, respectively macOS 10.7 and 10.13 or higher is required.

Examples

# 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

# Skip building on Python 2.7 on all platforms
CIBW_SKIP: cp27-*

# Skip Python 2.7 on Windows
CIBW_SKIP: cp27-win*

# Skip Python 2.7 on 32-bit Windows
CIBW_SKIP: cp27-win32

# Skip Python 2.7 and Python 3.5
CIBW_SKIP: cp27-* cp35-*

# Skip Python 3.6 on Linux
CIBW_SKIP: cp36-manylinux*

# Only build on Python 3 and skip 32-bit builds
CIBW_BUILD: cp3?-*
CIBW_SKIP: "*-win32 *-manylinux_i686"

# Only build PyPy and CPython 3
CIBW_BUILD: pp* cp3?-*

# Disable building PyPy wheels on all platforms
CIBW_SKIP: pp*

Build customization

CIBW_ENVIRONMENT

Set environment variables needed during the build

A space-separated list of environment variables to set during the build. Bash syntax should be used, even on Windows.

You must set this variable to pass variables to Linux builds (since they execute in a Docker container). It also works for the other platforms.

You can use $PATH syntax to insert other variables, or the $(pwd) syntax to insert the output of other shell commands.

To specify more than one environment variable, separate the assignments by spaces.

Platform-specific variants also available:
CIBW_ENVIRONMENT_MACOS | CIBW_ENVIRONMENT_WINDOWS | CIBW_ENVIRONMENT_LINUX

Examples

# Set some compiler flags
CIBW_ENVIRONMENT: "CFLAGS='-g -Wall' CXXFLAGS='-Wall'"

# Append a directory to the PATH variable (this is expanded in the build environment)
CIBW_ENVIRONMENT: "PATH=$PATH:/usr/local/bin"

# Set BUILD_TIME to the output of the `date` command
CIBW_ENVIRONMENT: "BUILD_TIME=$(date)"

# Supply options to `pip` to affect how it downloads dependencies
CIBW_ENVIRONMENT: "PIP_EXTRA_INDEX_URL=https://pypi.myorg.com/simple"

# Set two flags
CIBW_ENVIRONMENT: "BUILD_TIME=$(date) SAMPLE_TEXT=\"sample text\""

Note

cibuildwheel always defines the environment variable CIBUILDWHEEL=1. This can be useful for building wheels with optional extensions.

CIBW_BEFORE_ALL

Execute a shell command on the build system before any wheels are built.

Shell command to prepare a common part of the project (e.g. build or install libraries which does not depend on the specific version of Python).

This option is very useful for the Linux build, where builds take place in isolated Docker containers managed by cibuildwheel. This command will run inside the container before the wheel builds start. Note, if you're building both x86_64 and i686 wheels (the default), your build uses two different Docker images. In that case, this command will execute twice - once per build container.

The placeholder {package} can be used here; it will be replaced by the path to the package being built by cibuildwheel.

On Windows and macOS, the version of Python available inside CIBW_BEFORE_ALL is whatever is available on the host machine. On Linux, a modern Python version is available on PATH.

Platform-specific variants also available:
CIBW_BEFORE_ALL_MACOS | CIBW_BEFORE_ALL_WINDOWS | CIBW_BEFORE_ALL_LINUX

Examples

# build third party library
CIBW_BEFORE_ALL: make -C third_party_lib

# install system library
CIBW_BEFORE_ALL_LINUX: yum install -y libffi-dev

CIBW_BEFORE_BUILD

Execute a shell command preparing each wheel's build

A shell command to run before building the wheel. This option allows you to run a command in each Python environment before the pip wheel command. This is useful if you need to set up some dependency so it's available during the build.

If dependencies are required to build your wheel (for example if you include a header from a Python module), set this to pip install ., and the dependencies will be installed automatically by pip. However, this means your package will be built twice - if your package takes a long time to build, you might wish to manually list the dependencies here instead.

The active Python binary can be accessed using python, and pip with pip; cibuildwheel makes sure the right version of Python and pip will be executed. The placeholder {package} can be used here; it will be replaced by the path to the package being built by cibuildwheel.

The command is run in a shell, so you can write things like cmd1 && cmd2.

Platform-specific variants also available:
CIBW_BEFORE_BUILD_MACOS | CIBW_BEFORE_BUILD_WINDOWS | CIBW_BEFORE_BUILD_LINUX

Examples

# install your project and dependencies before building
CIBW_BEFORE_BUILD: pip install .

# install something required for the build
CIBW_BEFORE_BUILD: pip install pybind11

# chain commands using &&
CIBW_BEFORE_BUILD: yum install -y libffi-dev && pip install .

# run a script that's inside your project
CIBW_BEFORE_BUILD: bash scripts/prepare_for_build.sh

# if cibuildwheel is called with a package_dir argument, it's available as {package}
CIBW_BEFORE_BUILD: "{package}/bin/prepare_for_build.sh"

CIBW_REPAIR_WHEEL_COMMAND

Execute a shell command to repair each (non-pure Python) built wheel

Default:

  • on Linux: 'auditwheel repair -w {dest_dir} {wheel}'
  • on macOS: 'delocate-listdeps {wheel} && delocate-wheel --require-archs x86_64 -w {dest_dir} {wheel}'
  • on Windows: ''

A shell command to repair a built wheel by copying external library dependencies into the wheel tree and relinking them. The command is run on each built wheel (except for pure Python ones) before testing it.

The following placeholders must be used inside the command and will be replaced by cibuildwheel:

  • {wheel} for the absolute path to the built wheel
  • {dest_dir} for the absolute path of the directory where to create the repaired wheel.

The command is run in a shell, so you can run multiple commands like cmd1 && cmd2.

Platform-specific variants also available:
CIBW_REPAIR_WHEEL_COMMAND_MACOS | CIBW_REPAIR_WHEEL_COMMAND_WINDOWS | CIBW_REPAIR_WHEEL_COMMAND_LINUX

Examples

# don't repair macOS wheels
CIBW_REPAIR_WHEEL_COMMAND_MACOS: ""

# pass the `--lib-sdir .` flag to auditwheel on Linux
CIBW_REPAIR_WHEEL_COMMAND_LINUX: "auditwheel repair --lib-sdir . -w {dest_dir} {wheel}"

CIBW_MANYLINUX_X86_64_IMAGE, CIBW_MANYLINUX_I686_IMAGE, CIBW_MANYLINUX_PYPY_X86_64_IMAGE, CIBW_MANYLINUX_AARCH64_IMAGE, CIBW_MANYLINUX_PPC64LE_IMAGE, CIBW_MANYLINUX_S390X_IMAGE

Specify alternative manylinux docker images

An alternative Docker image to be used for building manylinux wheels. cibuildwheel will then pull these instead of the default images, quay.io/pypa/manylinux2010_x86_64, quay.io/pypa/manylinux2010_i686, pypywheels/manylinux2010-pypy_x86_64, quay.io/pypa/manylinux2014_aarch64, quay.io/pypa/manylinux2014_ppc64le, and quay.io/pypa/manylinux2014_s390x.

The value of this option can either be set to manylinux1, manylinux2010 or manylinux2014 to use a pinned version of the official manylinux images and PyPy manylinux images. Alternatively, set these options to any other valid Docker image name. Note that for PyPy, only the official manylinux2010 image is currently available. For architectures other than x86 (x86_64 and i686) manylinux2014 must be used because this is the first version of the manylinux specification that supports additional architectures.

Beware to specify a valid Docker image that can be used in the same way as the official, default Docker images: all necessary Python and pip versions need to be present in /opt/python/, and the auditwheel tool needs to be present for cibuildwheel to work. Apart from that, the architecture and relevant shared system libraries need to be manylinux1-, manylinux2010- or manylinux2014-compatible in order to produce valid manylinux1/manylinux2010/manylinux2014 wheels (see pypa/manylinux on GitHub, PEP 513, PEP 571 and PEP 599 for more details).

Note that auditwheel detects the version of the manylinux standard in the Docker image through the AUDITWHEEL_PLAT environment variable, as cibuildwheel has no way of detecting the correct --plat command line argument to pass to auditwheel for a custom image. If a Docker image does not correctly set this AUDITWHEEL_PLAT environment variable, the CIBW_ENVIRONMENT option can be used to do so (e.g., CIBW_ENVIRONMENT='AUDITWHEEL_PLAT="manylinux2010_$(uname -m)"').

Note that manylinux2014 doesn't support builds with Python 2.7 - when building with manylinux2014, skip Python 2.7 using CIBW_SKIP (see example below).

Examples

# build using the manylinux1 image to ensure manylinux1 wheels are produced
# skip PyPy, since there is no PyPy manylinux1 image
CIBW_MANYLINUX_X86_64_IMAGE: manylinux1
CIBW_MANYLINUX_I686_IMAGE: manylinux1
CIBW_SKIP: pp*

# build using the manylinux2014 image
CIBW_MANYLINUX_X86_64_IMAGE: manylinux2014
CIBW_MANYLINUX_I686_IMAGE: manylinux2014
CIBW_SKIP: cp27-manylinux*

# build using the latest manylinux2010 release, instead of the cibuildwheel
# pinned version
CIBW_MANYLINUX_X86_64_IMAGE: quay.io/pypa/manylinux2010_x86_64:latest
CIBW_MANYLINUX_I686_IMAGE: quay.io/pypa/manylinux2010_i686:latest

# build using a different image from the docker registry
CIBW_MANYLINUX_X86_64_IMAGE: dockcross/manylinux-x64
CIBW_MANYLINUX_I686_IMAGE: dockcross/manylinux-x86

CIBW_DEPENDENCY_VERSIONS

Specify how cibuildwheel controls the versions of the tools it uses

Options: pinned latest <your constraints file>

Default: pinned

If CIBW_DEPENDENCY_VERSIONS is pinned, cibuildwheel uses versions of tools like pip, setuptools, virtualenv that were pinned with that release of cibuildwheel. This represents a known-good set of dependencies, and is recommended for build repeatability.

If set to latest, cibuildwheel will use the latest of these packages that are available on PyPI. This might be preferable if these packages have bug fixes that can't wait for a new cibuildwheel release.

To control the versions of dependencies yourself, you can supply a pip constraints file here and it will be used instead.

Note

If you need different dependencies for each python version, provide them in the same folder with a -pythonXY suffix. e.g. if your CIBW_DEPENDENCY_VERSIONS=./constraints.txt, cibuildwheel will use ./constraints-python27.txt on Python 2.7, or fallback to ./constraints.txt if that's not found.

Platform-specific variants also available:
CIBW_DEPENDENCY_VERSIONS_MACOS | CIBW_DEPENDENCY_VERSIONS_WINDOWS

Note

This option does not affect the tools used on the Linux build - those versions are bundled with the manylinux image that cibuildwheel uses. To change dependency versions on Linux, use the CIBW_MANYLINUX_* options.

Examples

# use tools versions that are bundled with cibuildwheel (this is the default)
CIBW_DEPENDENCY_VERSIONS: pinned

# use the latest versions available on PyPI
CIBW_DEPENDENCY_VERSIONS: latest

# use your own pip constraints file
CIBW_DEPENDENCY_VERSIONS: ./constraints.txt

Testing

CIBW_TEST_COMMAND

Execute a shell command to test each built wheel

Shell command to run tests after the build. The wheel will be installed automatically and available for import from the tests. To ensure the wheel is imported by your tests (instead of your source copy), tests are run from a different directory. Use the placeholders {project} and {package} when specifying paths in your project.

  • {project} is an absolute path to the project root - the working directory where cibuildwheel was called.
  • {package} is the path to the package being built - the package_dir argument supplied to cibuildwheel on the command line.

The command is run in a shell, so you can write things like cmd1 && cmd2.

Platform-specific variants also available:
CIBW_TEST_COMMAND_MACOS | CIBW_TEST_COMMAND_WINDOWS | CIBW_TEST_COMMAND_LINUX

Examples

# run the project tests against the installed wheel using `nose`
CIBW_TEST_COMMAND: nosetests {project}/tests

# run the package tests using `pytest`
CIBW_TEST_COMMAND: pytest {package}/tests

CIBW_BEFORE_TEST

Execute a shell command before testing each wheel

A shell command to run in each test virtual environment, before your wheel is installed and tested. This is useful if you need to install a non pip package, change values of environment variables or perform multi step pip installation (e.g. installing scikit-build or cython before install test package)

The active Python binary can be accessed using python, and pip with pip; cibuildwheel makes sure the right version of Python and pip will be executed. The placeholder {package} can be used here; it will be replaced by the path to the package being built by cibuildwheel.

The command is run in a shell, so you can write things like cmd1 && cmd2.

Platform-specific variants also available:
CIBW_BEFORE_TEST_MACOS | CIBW_BEFORE_TEST_WINDOWS | CIBW_BEFORE_TEST_LINUX

Examples

# install test dependencies with overwritten environment variables.
CIBW_BEFORE_TEST: CC=gcc CXX=g++ pip install -r requirements.txt

# chain commands using &&
CIBW_BEFORE_TEST: rm -rf ./data/cache && mkdir -p ./data/cache

# install non pip python package
CIBW_BEFORE_TEST: cd some_dir; ./configure; make; make install

# install python packages that are required to install test dependencies
CIBW_BEFORE_TEST: pip install cmake scikit-build

CIBW_TEST_REQUIRES

Install Python dependencies before running the tests

Space-separated list of dependencies required for running the tests.

Platform-specific variants also available:
CIBW_TEST_REQUIRES_MACOS | CIBW_TEST_REQUIRES_WINDOWS | CIBW_TEST_REQUIRES_LINUX

Examples

# install pytest before running CIBW_TEST_COMMAND
CIBW_TEST_REQUIRES: pytest

# install specific versions of test dependencies
CIBW_TEST_REQUIRES: nose==1.3.7 moto==0.4.31

CIBW_TEST_EXTRAS

Install your wheel for testing using extras_require

Comma-separated list of extras_require options that should be included when installing the wheel prior to running the tests. This can be used to avoid having to redefine test dependencies in CIBW_TEST_REQUIRES if they are already defined in setup.py or setup.cfg.

Platform-specific variants also available:
CIBW_TEST_EXTRAS_MACOS | CIBW_TEST_EXTRAS_WINDOWS | CIBW_TEST_EXTRAS_LINUX

Examples

# will cause the wheel to be installed with `pip install <wheel_file>[test,qt]`
CIBW_TEST_EXTRAS: test,qt

Other

CIBW_BUILD_VERBOSITY

Increase/decrease the output of pip wheel

An number from 1 to 3 to increase the level of verbosity (corresponding to invoking pip with -v, -vv, and -vvv), between -1 and -3 (-q, -qq, and -qqq), or just 0 (default verbosity). These flags are useful while debugging a build when the output of the actual build invoked by pip wheel is required.

Platform-specific variants also available:
CIBW_BUILD_VERBOSITY_MACOS | CIBW_BUILD_VERBOSITY_WINDOWS | CIBW_BUILD_VERBOSITY_LINUX

Examples

# increase pip debugging output
CIBW_BUILD_VERBOSITY: 1

Command line options

usage: cibuildwheel [-h] [--platform {auto,linux,macos,windows}]
                    [--output-dir OUTPUT_DIR] [--print-build-identifiers]
                    [package_dir]

Build wheels for all the platforms.

positional arguments:
  package_dir           Path to the package that you want wheels for. Must be
                        a subdirectory of the working directory. When set, the
                        working directory is still considered the 'project'
                        and is copied into the Docker container on Linux.
                        Default: the working directory.

optional arguments:
  -h, --help            show this help message and exit
  --platform {auto,linux,macos,windows}
                        Platform to build for. For "linux" you need docker
                        running, on Mac or Linux. For "macos", you need a Mac
                        machine, and note that this script is going to
                        automatically install MacPython on your system, so
                        don't run on your development machine. For "windows",
                        you need to run in Windows, and it will build and test
                        for all versions of Python. Default: auto.
  --output-dir OUTPUT_DIR
                        Destination folder for the wheels.
  --print-build-identifiers
                        Print the build identifiers matched by the current
                        invocation and exit.