Skip to content

Improve docs on how to skip free-threaded builds #2549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 12, 2025
Merged

Improve docs on how to skip free-threaded builds #2549

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ff0149a
Improve docs on how to skip free-threaded builds
joerick Aug 11, 2025
e8c67a5
Add a reference to the Python Free-Threading Guide
joerick Aug 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 28 additions & 22 deletions docs/options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ Windows arm64 platform support is experimental.

See the [cibuildwheel 2 documentation](https://cibuildwheel.pypa.io/en/2.x/) for past end-of-life versions of Python.

#### Examples
#### Examples {: #build-skip-examples }

!!! tab examples "pyproject.toml"

Expand Down Expand Up @@ -106,6 +106,12 @@ See the [cibuildwheel 2 documentation](https://cibuildwheel.pypa.io/en/2.x/) for

# Disable building PyPy wheels on all platforms
skip = "pp*"

# Disable free-threading builds on all platforms
skip = "cp3??t-*"

# Disable free-threading builds on Windows
skip = "cp3??t-win*"
```

!!! tab examples "Environment variables"
Expand Down Expand Up @@ -137,11 +143,15 @@ See the [cibuildwheel 2 documentation](https://cibuildwheel.pypa.io/en/2.x/) for

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

Separate multiple selectors with a space.
# Disable free-threading builds on all platforms
CIBW_SKIP: "cp3??t-*"

# Disable free-threading builds on Windows
CIBW_SKIP: "cp3??t-win*"
```

Separate multiple selectors with a space.

It is generally recommended to set `CIBW_BUILD` as an environment variable, though `skip`
tends to be useful in a config file; you can statically declare that you don't
Expand Down Expand Up @@ -344,13 +354,9 @@ values are:

- `cpython-prerelease`: Enables beta versions of Pythons if any are available
(May-July, approximately).
- `cpython-freethreading`: [PEP 703](https://www.python.org/dev/peps/pep-0703)
introduced variants of CPython that can be built without the Global
Interpreter Lock (GIL). Those variants are also known as free-threaded /
no-gil. This will enable building these wheels for 3.13, which was considered
experimental. The build identifiers for those variants have a `t` suffix in
their `python_tag` (e.g. `cp313t-manylinux_x86_64`). Starting in 3.14,
free-threaded builds are no longer experimental, so this enable is not needed.
- `cpython-freethreading`: Enable experimental free-threaded builds for CPython 3.13.
Free-threading wheels for 3.14+ are available without this flag, as it's [no
longer considered experimental](https://peps.python.org/pep-0779/).
- `pypy`: Enable PyPy.
- `pypy-eol`: Enable PyPy versions that have passed end of life (if still available).
- `graalpy`: Enable GraalPy.
Expand All @@ -368,7 +374,15 @@ values are:
that version of Python will become available without this flag.

!!! note
Free threading was experimental in 3.13: [What’s New In Python 3.13](https://docs.python.org/3.13/whatsnew/3.13.html#free-threaded-cpython)
[PEP 703](https://www.python.org/dev/peps/pep-0703) introduced variants of
CPython that can be built without the Global Interpreter Lock (GIL). Those
variants are also known as free-threaded / no-gil. The build identifiers for
those variants have a `t` suffix in their `python_tag` (e.g.
`cp313t-manylinux_x86_64`).

Free threading was [experimental in 3.13](https://docs.python.org/3.13/whatsnew/3.13.html#free-threaded-cpython), so it required an explicit enable flag. But, as noted above, free-threading doesn't require an enable flag for 3.14+.

For more info on building for free-threading, see the [Python Free-Threading Guide](https://py-free-threading.github.io/).

Default: empty.

Expand All @@ -392,12 +406,8 @@ without disabling your other enables.

```toml
[tool.cibuildwheel]
# Enable free-threaded support
enable = ["cpython-freethreading"]

# Skip building free-threaded compatible wheels on Windows
# Enable free-threaded support for CPython 3.13
enable = ["cpython-freethreading"]
skip = "*t-win*"

# Include all PyPy versions
enable = ["pypy", "pypy-eol"]
Expand All @@ -410,18 +420,14 @@ without disabling your other enables.
# Include latest Python beta
CIBW_ENABLE: cpython-prerelease

# Include free-threaded support
# Include free-threaded support for CPython 3.13
CIBW_ENABLE: cpython-freethreading

# Include both
CIBW_ENABLE: cpython-prerelease cpython-freethreading

# Skip building free-threaded compatible wheels on Windows
CIBW_ENABLE: cpython-freethreading
CIBW_SKIP: *t-win*

# Include all PyPy versions
CIBW_ENABLE = pypy pypy-eol
CIBW_ENABLE: pypy pypy-eol
```


Expand Down
Loading