Python support for free threading

Starting with the 3.13 release, CPython has 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.

Some third-party packages, in particular oneswith anextension module, may not be ready for use in afree-threaded build, and will re-enable theGIL.

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 “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

In the free-threaded build, some objects areimmortal.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.

As of the 3.14 release, immortalization is limited to:

  • Code constants: numeric literals, string literals, and tuple literalscomposed of other constants.

  • Strings interned bysys.intern().

Frame objects

It is not safe to accessframe.f_locals from aframeobject if that frame is currently executing in another thread, and doing so maycrash the interpreter.

Iterators

It is generally not thread-safe to access the same iterator object frommultiple threads concurrently, and threads may see duplicate or missingelements.

Single-threaded performance

The free-threaded build has additional overhead when executing Python codecompared to the default GIL-enabled build. The amount of overhead dependson the workload and hardware. On the pyperformance benchmark suite, theaverage overhead ranges from about 1% on macOS aarch64 to 8% on x86-64 Linuxsystems.

Behavioral changes

This section describes CPython behavioural changes with the free-threadedbuild.

Context variables

In the free-threaded build, the flagthread_inherit_contextis set to true by default which causes threads created withthreading.Thread to start with a copy of theContext() of the caller ofstart(). In the default GIL-enabled build, the flagdefaults to false so threads start with anemptyContext().

Warning filters

In the free-threaded build, the flagcontext_aware_warningsis set to true by default. In the default GIL-enabled build, the flag defaultsto false. If the flag is true then thewarnings.catch_warningscontext manager uses a context variable for warning filters. If the flag isfalse thencatch_warnings modifies the global filters list,which is not thread-safe. See thewarnings module for more details.