Setting up CI
Currently the setup-python
GitHub Action does not
support installing a
free-threaded build. For now, here are some relatively easy ways:
Ubuntu Linux CI setup via deadsnakes-action
The easiest way to get a free-threaded Python build on a CI runner is with the
deadsnakes
Ubuntu PPA and the deadsnakes-action
GitHub Action:
jobs:
free-threaded:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@...
- uses: deadsnakes/action@...
with:
python-version: 3.13-dev
nogil: true
You should replace the ellipses with versions for the actions. If there is a newer CPython 3.13 release available since this document was written or updated, use that version instead.
Windows CI setup via custom PowerShell
For installing a free-threaded build of Python on a Windows CI runner
(runs-on: windows-latest
), you can download and install directly from
https://www.python.org/ftp/python/ as
shown in the following PowerShell snippet (noting that the free-threaded
binary is named python{version}t.exe
, where the "t" is for free-"t"hreaded).
For more tips see the docs on silent installation and options on
Windows.
jobs:
free-threaded:
runs-on: windows-latest
steps:
- uses: actions/checkout@...
- name: custom python install script
shell: pwsh
run: |
$pythonInstallerUrl = "https://www.python.org/ftp/python/3.13.0/python-3.13.0rc2-amd64.exe"
Invoke-WebRequest $pythonInstallerUrl -OutFile setup-python.exe
Start-Process "setup-python.exe" -argumentlist "/quiet PrependPath=1 TargetDir=C:\Python313 Include_freethreaded=1" -wait
C:\Python313\python3.13t.exe -m pip install -r requirements.txt
C:\Python313\python3.13t.exe -c "import sys; print(sys._is_gil_enabled())"
Building free-threaded wheels with cibuildwheel
cibuildwheel has support
for building free-threaded wheels on all platforms. If your project releases
nightly wheels, we suggest configuring cibuildwheel
to build nightly
free-threaded wheels.
If your project depends on Cython or the NumPy C API, you will need to install a Cython nightly wheel in the build, as the newest stable release of Cython cannot generate code that will compile under the free-threaded build. Cython 3.1.0 and NumPy 2.1.0 will be or are the first stable releases to support free-threaded python. See the project tracker for more detailed information about projects you may depend on.
You can install nightly wheels for both Cython and NumPy using the following install command:
pip install -i https://pypi.anaconda.org/scientific-python-nightly-wheels/simple cython numpy
To ensure wheels are built correctly under cibuildwheel, you will need to specify the following variables in the environment for the cibuildwheel action:
- name: Build wheels
uses: pypa/cibuildwheel@...
env:
CIBW_PRERELEASE_PYTHONS: true
CIBW_FREE_THREADED_SUPPORT: true
CIBW_BUILD: cp313t-${{ matrix.buildplat }}
# TODO:
# remove when a released cython can build free-threaded extensions
CIBW_BUILD_FRONTEND: 'pip; args: --no-build-isolation'
As above, replace the ellipses with a cibuildwheel
version.
If for some reason disabling build isolation is unworkable, you can also tell pip about the nightly wheel index and it will use it in an isolated build. To do this, set:
CIBW_BUILD_FRONTEND: 'pip; args: --pre --extra-index-url "https://pypi.anaconda.org/scientific-python-nightly-wheels/simple"'
Many projects use build
instead of pip
for the build frontend. See the
cibuildwheel
docs for more information about how to pass arguments to build
and pip
. See
this
comment on
the build
issue tracker if you need to use build
and cannot disable build
isolation.
Note that nightly wheels may not be available on all platforms yet. Windows wheels, in particular, are not currently available for NumPy or projects that depend on NumPy (e.g., SciPy).
You will also likely need to manually pass -Xgil=0
or set PYTHON_GIL=0
in
your shell environment while running tests to ensure the GIL is actually
disabled during tests, at least until you can register that your extension
modules support disabling the GIL via Py_mod_gil
and all of your runtime test
dependencies do the same. See the porting guide for more
information about declaring support for free-threaded python in your extension.