Skip to content

Handling dependencies that don’t support free-threading#

Build dependencies that don't support free-threading#

CFFI support for the free-threaded Python build#

CFFI added support for the free-threaded build of Python 3.14 in version 2.0.0b1. You can install it by passing a version constraint to pip:

python -m pip install cffi>=2.0.0b1

You can also pass --pre to pip but that may also bring in other unwanted prereleases for projects with big dependency trees.

If you want to force CFFI 2.0.0b1 to be used, you can use the following pyproject.toml snippet:

[build-system]
requires = [
  "cffi>=2.0.0b1",
]

You can also use the python_version environment marker to specify the constraint is only valid for Python 3.14 and newer:

[build-system]
requires = [
  "cffi>=2.0.0b1; python_version >= '3.14'",
  "cffi; python_version < '3.14'",
]

You can declare a runtime dependency in the project.dependencies section using the same syntax.

CFFI does not support the free-threaded build of Python 3.13.

mypyc#

The mypyc bindings generator does not yet support the free-threaded build. Usually mypyc is used with projects that can be straightforwardly used in a pure-python mode. We suggest using that and waiting for upstream support in mypyc to get a compiled extension in the future.

Other bindings generators#

Cython, nanobind, pybind11, and PyO3 all fully support the free-threaded build. See the documentation of those projects for more details about using them with the free-threaded interpreter.

Runtime dependencies that don't support free-threading#

Depending on PyYAML - use PyYAML-ft#

If your library depends on PyYAML, you will need to take extra care to use it with free-threaded Python. PyYAML currently does not support free-threading and has some thread-safety issues. Its maintainers have decided to not port PyYAML before free-threading and Cython support for it have been more extensively tested.

That's why we've created a fork of PyYAML with support for free-threading called PyYAML-ft. PyYAML users can switch to this fork if they want to test their code with the free-threaded build.

Currently, PyYAML-ft only supports Python 3.13 and 3.13t (i.e. the free-threaded build of 3.13). To switch to it, you can add the following to your requirements.txt:

PyYAML; python_version < '3.13'
PyYAML-ft; python_version >= '3.13'

If you define your dependencies in pyproject.toml, then you can do the following:

dependencies = [
  "PyYAML; python_version<'3.13'",
  "PyYAML-ft; python_version>='3.13'",
]

Different module name#

PyYAML-ft uses a different module name (namely yaml_ft) than upstream PyYAML on purpose, so that both can be installed in an environment at the same time.

If your library depends on both for different Python versions, you can do the following for ease of use:

try:
    import yaml_ft as yaml
except ModuleNotFoundError:
    import yaml