docs: clarify environment precedence (#2905)

This commit is contained in:
Himanshu Agrawal
2026-06-10 09:34:19 -04:00
committed by GitHub
parent 2f9a352352
commit 55c8985c12
2 changed files with 13 additions and 5 deletions
+7 -5
View File
@@ -64,10 +64,12 @@ 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](https://toml.io) practice. Anything placed in subsections
named after a platform will only affect those platforms. 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 variables will take
precedence if defined.
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. 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`, will take precedence if defined.
The example above using environment variables could have been written like this:
@@ -178,7 +180,7 @@ on Python 3.11, and will have `environment = {FOO="BAZ", "PYTHON"="MONTY", "HAM"
In the TOML configuration, you can choose how tables and lists are inherited.
By default, all values are overridden completely (`"none"`) but sometimes you'd
rather `"append"` or `"prepend"` to an existing list or table. You can do this
with the `inherit` table in overrides. For example, if you want to add an environment
with the `inherit` table 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: