Python experimental support for free threading¶
Starting with the 3.13 release, CPython has experimental support for a build ofPython calledfree threading where theglobal interpreter lock(GIL) is disabled. Free-threaded execution allows for full utilization of theavailable processing power by running threads in parallel on available CPU cores.While not all software will benefit from this automatically, programsdesigned with threading in mind will run faster on multi-core hardware.
The free-threaded mode is experimental and work is ongoing to improve it:expect some bugs and a substantial single-threaded performance hit.
This document describes the implications of free threadingfor Python code. SeeC API Extension Support for Free Threading for information onhow to write C extensions that support the free-threaded build.
See also
PEP 703 – Making the Global Interpreter Lock Optional in CPython for anoverall description of free-threaded Python.
Installation¶
Starting with Python 3.13, the official macOS and Windows installersoptionally support installing free-threaded Python binaries. The installersare available athttps://www.python.org/downloads/.
For information on other platforms, see theInstalling a Free-Threaded Python, acommunity-maintained installation guide for installing free-threaded Python.
When building CPython from source, the--disable-gil configure optionshould be used to build a free-threaded Python interpreter.
Identifying free-threaded Python¶
To check if the current interpreter supports free-threading,python-VVandsys.version contain “experimental free-threading build”.The newsys._is_gil_enabled() function can be used to check whetherthe GIL is actually disabled in the running process.
Thesysconfig.get_config_var("Py_GIL_DISABLED") configuration variable canbe used to determine whether the build supports free threading. If the variableis set to1, then the build supports free threading. This is the recommendedmechanism for decisions related to the build configuration.
The global interpreter lock in free-threaded Python¶
Free-threaded builds of CPython support optionally running with the GIL enabledat runtime using the environment variablePYTHON_GIL orthe command-line option-Xgil.
The GIL may also automatically be enabled when importing a C-API extensionmodule that is not explicitly marked as supporting free threading. A warningwill be printed in this case.
In addition to individual package documentation, the following websites trackthe status of popular packages support for free threading:
Thread safety¶
The free-threaded build of CPython aims to provide similar thread-safetybehavior at the Python level to the default GIL-enabled build. Built-intypes likedict,list, andset use internal locksto protect against concurrent modifications in ways that behave similarly tothe GIL. However, Python has not historically guaranteed specific behavior forconcurrent modifications to these built-in types, so this should be treatedas a description of the current implementation, not a guarantee of current orfuture behavior.
Note
It’s recommended to use thethreading.Lock or other synchronizationprimitives instead of relying on the internal locks of built-in types, whenpossible.
Known limitations¶
This section describes known limitations of the free-threaded CPython build.
Immortalization¶
The free-threaded build of the 3.13 release makes some objectsimmortal.Immortal objects are not deallocated and have reference counts that arenever modified. This is done to avoid reference count contention that wouldprevent efficient multi-threaded scaling.
An object will be made immortal when a new thread is started for the first timeafter the main thread is running. The following objects are immortalized:
function objects declared at the module level
method descriptors
code objects
module objects and their dictionaries
classes (type objects)
Because immortal objects are never deallocated, applications that create manyobjects of these types may see increased memory usage. This is expected to beaddressed in the 3.14 release.
Additionally, numeric and string literals in the code as well as stringsreturned bysys.intern() are also immortalized. This behavior isexpected to remain in the 3.14 free-threaded build.
Frame objects¶
It is not safe to accessframe objects from otherthreads and doing so may cause your program to crash . This means thatsys._current_frames() is generally not safe to use in a free-threadedbuild. Functions likeinspect.currentframe() andsys._getframe()are generally safe as long as the resulting frame object is not passed toanother thread.
Iterators¶
Sharing the same iterator object between multiple threads is generally notsafe and threads may see duplicate or missing elements when iterating or crashthe interpreter.
Single-threaded performance¶
The free-threaded build has additional overhead when executing Python codecompared to the default GIL-enabled build. In 3.13, this overhead is about40% on thepyperformance suite.Programs that spend most of their time in C extensions or I/O will seeless of an impact. The largest impact is because the specializing adaptiveinterpreter (PEP 659) is disabled in the free-threaded build. We expectto re-enable it in a thread-safe way in the 3.14 release. This overhead isexpected to be reduced in upcoming Python release. We are aiming for anoverhead of 10% or less on the pyperformance suite compared to the defaultGIL-enabled build.