Skip to content

Frequently seen errors and how to fix them

These are error messages that we see come up often when working with code or development workflows that have not been updated to accommodate the free-threaded build. We also provide suggested fixes. Please send in pull requests to the repository for this document if you run into any confusing free-threading-specific errors that you suspect apply to other libraries and aren't covered here.

Cython compilation errors: unknown type name '__pyx_vectorcallfunc'

This happens if you try to build a Cython extension for the free-threaded build using the current stable release of Cython (3.0.11 at the time of writing). The current stable release of Cython does not support the free-threaded build. You must either install the Cython 3.1 beta by passing --pre to pip:

pip install cython --pre

use the nightly wheel:

pip install -i https://pypi.anaconda.org/scientific-python-nightly-wheels/simple cython

or build Cython from the master branch on Github.

See the porting guide for more detail about porting Cython code to work under free-threading.

The beta and nightly wheel are pure-python builds, so they work on all architectures. The pure-python version of Cython is usually only marginally slower than a compiled version, so you should default to installing a pre-release wheel in CI instead of compiling Cython, which can take up to a few minutes on some CI runners.

You may wonder why pip install cython succeeds on the current stable Cython release if free-threaded Python is not supported. This is because Cython ships a pure-python wheel tagged with py2.py3-none-any, which pip will install if it cannot find another wheel that is compatible. Since there isn't a free-threaded wheel, pip installs the pure Python wheel instead, and there is no opportunity to catch this case at install time in e.g. a setup.py file. The Cython 3.1 release will fix this problem once and for all.

pip install jupyter fails

This happens because some of the dependencies of the jupyter project on PyPI do not yet support the free-threaded build. In particular, argon2-cffi uses a C extension provided by the argon2-cffi-bindings project, which in turn uses CFFI to generate bindings for the argon2 C password hashing library.

Because CFFI does not yet ship a stable release that supports the free-threaded build, even if you have a compiler environment properly set up, the argon2-cffi-bindings build will fail.

For now, we do not recommend trying to install jupyterlab into an environment managed by a free-threaded Python interpreter. Instead, we suggest installing a free-threaded Python kernel into a jupyterlab installation managed by a GIL-enabled python interpreter. See our instructions for installing a free-threaded Jupyter kernel for more details.

That said, it is possible to install jupyter into a free-threaded Python environment and launch jupyterlab, see this issue for more details.

What does "Py_LIMITED_API is currently incompatible with Py_GIL_DISABLED" mean?

You might see an error with this message generated by setuptools, but other tools might generate similar errors for the same reason.

The ultimate problem is that CPython does not yet offer a stable ABI on the free-threaded build. See this CPython issue for more details. This means it's not yet possible to build an extension that any CPython version can import and instead libraries have to distribute one wheel for each version of free-threaded CPython. A future version of CPython will likely support a new version of the stable ABI that works correctly with both the GIL-enabled and free-threaded builds.

Until then, tools or libraries that default to using the stable ABI via the limited API will generate build errors on the free-threaded build. The fix is usually to disable the Py_LIMITED_API declaration that triggers use of the stable ABI on the free-threaded build by using the following incantation:

import sysconfig
FREETHREADED_BUILD = bool(sysconfig.get_config_var("Py_GIL_DISABLED"))

If you spell it this way, FREETHREADED_BUILD will be False on the GIL-enabled build and True for free-threaded builds.