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 a release of Cython that does not support it (\<3.1.0). See the porting guide for more details about porting Cython code to work under free-threading.

What does RuntimeWarning: The global interpreter lock (GIL) has been enabled mean?#

This happens when python imports a module defined in a native extension that does not explicitly declare support for running without the GIL. By default, native extensions do not support running without the GIL because of the long history of extensions assuming the GIL locks concurrent access to extension internals. As a precaution, when the free-threaded Python build imports such an extension, it assumes that the GIL is necessary to run the extension, and enables the GIL at runtime.

If you have control over the code in the native extension, then you should update the extension to support the free-threaded build. See the guide section on that topic. If you do not control the extension or simply want to test running with the GIL disabled despite the extension not explicitly supporting it, then you can set either the PYTHON_GIL environment variable or the -X gil command-like flag for the python interpreter to 0 (i.e. the GIL is disabled). This skips the runtime check for whether extensions support running with the GIL disabled. See the section on running free-threaded Python for more details.

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.