cibuildwheel/docs/configuration.md

title, ref

title	ref
Configuration	configuration

Configuration methods

cibuildwheel can either be configured using environment variables, or from config file such as pyproject.toml.

This page describes how to set options. For a full list of available options, see the options reference.

Environment variables {: #environment-variables}

Environment variables can be set in your CI config. For example, to configure cibuildwheel to run tests, add the following YAML to your CI config file:

!!! tab "GitHub Actions"

> .github/workflows/*.yml ([docs](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables)) (can be global, in job, or in step)

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

!!! tab "Azure Pipelines"

> azure-pipelines.yml ([docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/variables))

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

!!! tab "CircleCI"

> .circleci/config.yml ([docs](https://circleci.com/docs/2.0/configuration-reference/#environment))

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

!!! tab "Gitlab CI"

> .gitlab-ci.yml ([docs](https://docs.gitlab.com/ci/yaml/#variables))

```yaml
linux:
  variables:
    CIBW_TEST_REQUIRES: pytest
    CIBW_TEST_COMMAND: "pytest {project}/tests"
```

Configuration file {: #configuration-file}

You can configure cibuildwheel with a config file, such as pyproject.toml. Options have the same names as the environment variable overrides, but are placed in [tool.cibuildwheel] and are lower case, with dashes, following common TOML practice. Anything placed in subsections named after a platform will only affect those platforms. Platform-specific values replace the corresponding global value for that platform; table options are not merged key by key unless you configure inheritance. Lists can be used instead of strings for items that are naturally a list. Multiline strings also work just like in the environment variables. Environment variable overrides, such as CIBW_TEST_COMMAND and CIBW_TEST_COMMAND_LINUX, take precedence if defined.

The example above using environment variables could have been written like this:

[tool.cibuildwheel]
test-requires = "pytest"
test-command = "pytest ./tests"

The complete set of defaults for the current version of cibuildwheel are shown below:

{% include "../cibuildwheel/resources/defaults.toml" %}

!!! tip Static configuration works across all CI systems, and can be used locally if you run cibuildwheel --platform linux. This is preferred, but environment variables are better if you need to change per-matrix element (CIBW_BUILD is often in this category, for example), or if you cannot or do not want to change a pyproject.toml file. You can specify a different file to use with --config-file on the command line, as well.

Configuration overrides {: #overrides }

One feature specific to the configuration files is the ability to override settings based on selectors. To use, add a tool.cibuildwheel.overrides array, and specify a select string, referencing the build identifier (not wheel name!). Then any options you set will only apply to items that match that selector. These are applied in order, with later matches overriding earlier ones if multiple selectors match. Environment variables always override static configuration.

A few of the options below have special handling in overrides. A different before-all will trigger a new container to launch on Linux, and cannot be overridden on macOS or Windows. Overriding the image on linux will also trigger new containers, one per image.

!!! note "Some commands are not supported"

The ``output-dir``, ``build``, ``skip``, ``test_skip`` selectors, and architectures cannot be overridden.

By default, values in an override replace values from the main configuration or earlier overrides. You can instead extend a list or table option by setting an inherit rule for it.

Examples:

[tool.cibuildwheel.linux]
before-all = "yum install mylib"
test-command = "echo 'installed'"

[[tool.cibuildwheel.overrides]]
select = "*-musllinux*"
before-all = "apk add mylib"

This example will override the before-all command on musllinux only, but will still run the test-command. Note the double brackets, this is an array in TOML, which means it can be given multiple times.

[tool.cibuildwheel]
# Normal options, etc.
manylinux-x86_64-image = "manylinux_2_34"

[[tool.cibuildwheel.overrides]]
select = "cp39-*"
manylinux-x86_64-image = "manylinux2014"

[[tool.cibuildwheel.overrides]]
select = "cp3{10,11}-*"
manylinux-x86_64-image = "manylinux_2_28"

This example will build CPython 3.9 wheels on manylinux2014, CPython 3.10-3.11 wheels on manylinux_2_28, and manylinux_2_34 wheels for any newer Python (like 3.14).

[tool.cibuildwheel]
environment = {FOO="BAR", "HAM"="EGGS"}
test-command = ["pyproject"]

[[tool.cibuildwheel.overrides]]
select = "cp311*"

inherit.test-command = "prepend"
test-command = ["pyproject-before"]

inherit.environment="append"
environment = {FOO="BAZ", "PYTHON"="MONTY"}

[[tool.cibuildwheel.overrides]]
select = "cp311*"
inherit.test-command = "append"
test-command = ["pyproject-after"]

This example will provide the command "pyproject-before && pyproject && pyproject-after" on Python 3.11, and will have environment = {FOO="BAZ", "PYTHON"="MONTY", "HAM"="EGGS"}.

Option inheritance {: #inherit }

As cibuildwheel reads its configuration, each layer normally replaces the value from the previous layer. The layers, from lowest to highest precedence, are:

1. cibuildwheel's defaults
2. [tool.cibuildwheel]
3. [tool.cibuildwheel.<platform>]
4. matching [[tool.cibuildwheel.overrides]] entries, in order
5. CIBW_<OPTION>
6. CIBW_<OPTION>_<PLATFORM>

For list and table options, you can use an inherit rule to merge a value with the value accumulated from the preceding layers instead. The available rules are "none" (replace the previous value, the default), "append", and "prepend".

In pyproject.toml, set the rule in the same table as the value it applies to. For example, this adds Twine checks to the default audit configuration:

[tool.cibuildwheel]
inherit.audit-requires = "append"
inherit.audit-command = "append"
audit-requires = ["twine"]
audit-command = "twine check {wheel}"

Inheritance can also combine global and platform-specific configuration. This example runs a Linux-specific setup command before the global command:

[tool.cibuildwheel]
before-all = "make -C third_party_lib"

[tool.cibuildwheel.linux]
inherit.before-all = "prepend"
before-all = "yum install -y libffi-devel"

The same mechanism remains available in overrides. For example, if you want to add an environment variable for CPython 3.11, without inherit you'd have to repeat all the original environment variables in the override. With inherit, it's just:

[[tool.cibuildwheel.overrides]]
select = "cp311*"
inherit.environment = "append"
environment.NEWVAR = "Added!"

For a table, "append" will replace a key if it exists, while "prepend" will only add a new key, older keys take precedence.

Lists are also supported (and keep in mind that commands are lists). For example, you can print a message before and after a wheel is repaired:

[[tool.cibuildwheel.overrides]]
select = "*"
inherit.repair-wheel-command = "prepend"
repair-wheel-command = "echo 'Before repair'"

[[tool.cibuildwheel.overrides]]
select = "*"
inherit.repair-wheel-command = "append"
repair-wheel-command = "echo 'After repair'"

As seen in this example, you can have multiple overrides match - they match top to bottom, with the config being accumulated.

For environment variables, specify the rules in CIBW_INHERIT. Rules are separated by semicolons and use lowercase option names. A rule without an explicit value defaults to append:

CIBW_AUDIT_REQUIRES: twine
CIBW_AUDIT_COMMAND: "twine check {wheel}"
CIBW_INHERIT: "audit-requires; audit-command"

To control a platform-specific environment variable, add the lowercase platform suffix to the option name. For example, this prepends CIBW_BEFORE_ALL_LINUX to the value accumulated from the lower-precedence layers:

CIBW_BEFORE_ALL_LINUX: yum install -y libffi-devel
CIBW_INHERIT: "before-all-linux: prepend"