Getting started

Before getting to CI setup, it can be convenient to test cibuildwheel locally to quickly iterate and track down issues without having to commit each change, push, and then check CI logs.

Install cibuildwheel and run a build like this:

# run using uv
uvx cibuildwheel

# or pipx
pipx run cibuildwheel

# or, install it first
pip install cibuildwheel
cibuildwheel

Tip

You can pass the --platform linux option to cibuildwheel to build Linux wheels, even if you're not on Linux. On most machines, the easiest builds to try are the Linux builds. You don't need any software installed except a Docker daemon, such as Docker Desktop. Each platform that cibuildwheel supports has its own system requirements and platform-specific behaviors. See the platforms page for details.

You should see the builds taking place. You can experiment with options using pyproject.toml or environment variables.

pyproject.toml

If you write your options into pyproject.toml, you can work on your options locally, and they'll be automatically picked up when running in CI.

pyproject.toml

[tool.cibuildwheel]
before-all = "uname -a"

Then invoke cibuildwheel, like:

cibuildwheel

Environment variables

cibuildwheel will read config from the environment. Syntax varies, depending on your shell:

POSIX shell (Linux/macOS)

# run a command to set up the build system
export CIBW_BEFORE_ALL='uname -a'

cibuildwheel

CMD (Windows)

set CIBW_BEFORE_ALL='uname -a'

cibuildwheel