| 1 |
.. _freethreading-python-howto: |
| 2 |
|
| 3 |
********************************* |
| 4 |
Python support for free threading |
| 5 |
********************************* |
| 6 |
|
| 7 |
Starting with the 3.13 release, CPython has support for a build of |
| 8 |
Python called :term:`free threading` where the :term:`global interpreter lock` |
| 9 |
(GIL) is disabled. Free-threaded execution allows for full utilization of the |
| 10 |
available processing power by running threads in parallel on available CPU cores. |
| 11 |
While not all software will benefit from this automatically, programs |
| 12 |
designed with threading in mind will run faster on multi-core hardware. |
| 13 |
|
| 14 |
Some third-party packages, in particular ones |
| 15 |
with an :term:`extension module`, may not be ready for use in a |
| 16 |
free-threaded build, and will re-enable the :term:`GIL`. |
| 17 |
|
| 18 |
This document describes the implications of free threading |
| 19 |
for Python code. See :ref:`freethreading-extensions-howto` for information on |
| 20 |
how to write C extensions that support the free-threaded build. |
| 21 |
|
| 22 |
.. seealso:: |
| 23 |
|
| 24 |
:pep:`703` – Making the Global Interpreter Lock Optional in CPython for an |
| 25 |
overall description of free-threaded Python. |
| 26 |
|
| 27 |
|
| 28 |
Installation |
| 29 |
============ |
| 30 |
|
| 31 |
Starting with Python 3.13, the official macOS and Windows installers |
| 32 |
optionally support installing free-threaded Python binaries. The installers |
| 33 |
are available at https://www.python.org/downloads/. |
| 34 |
|
| 35 |
For information on other platforms, see the `Installing a Free-Threaded Python |
| 36 |
<https://py-free-threading.github.io/installing-cpython/>`_, a |
| 37 |
community-maintained installation guide for installing free-threaded Python. |
| 38 |
|
| 39 |
When building CPython from source, the :option:`--disable-gil` configure option |
| 40 |
should be used to build a free-threaded Python interpreter. |
| 41 |
|
| 42 |
|
| 43 |
Identifying free-threaded Python |
| 44 |
================================ |
| 45 |
|
| 46 |
To check if the current interpreter supports free-threading, :option:`python -VV <-V>` |
| 47 |
and :data:`sys.version` contain "free-threading build". |
| 48 |
The new :func:`sys._is_gil_enabled` function can be used to check whether |
| 49 |
the GIL is actually disabled in the running process. |
| 50 |
|
| 51 |
The ``sysconfig.get_config_var("Py_GIL_DISABLED")`` configuration variable can |
| 52 |
be used to determine whether the build supports free threading. If the variable |
| 53 |
is set to ``1``, then the build supports free threading. This is the recommended |
| 54 |
mechanism for decisions related to the build configuration. |
| 55 |
|
| 56 |
|
| 57 |
The global interpreter lock in free-threaded Python |
| 58 |
=================================================== |
| 59 |
|
| 60 |
Free-threaded builds of CPython support optionally running with the GIL enabled |
| 61 |
at runtime using the environment variable :envvar:`PYTHON_GIL` or |
| 62 |
the command-line option :option:`-X gil`. |
| 63 |
|
| 64 |
The GIL may also automatically be enabled when importing a C-API extension |
| 65 |
module that is not explicitly marked as supporting free threading. A warning |
| 66 |
will be printed in this case. |
| 67 |
|
| 68 |
In addition to individual package documentation, the following websites track |
| 69 |
the status of popular packages support for free threading: |
| 70 |
|
| 71 |
* https://py-free-threading.github.io/tracking/ |
| 72 |
* https://hugovk.github.io/free-threaded-wheels/ |
| 73 |
|
| 74 |
|
| 75 |
Thread safety |
| 76 |
============= |
| 77 |
|
| 78 |
The free-threaded build of CPython aims to provide similar thread-safety |
| 79 |
behavior at the Python level to the default GIL-enabled build. Built-in |
| 80 |
types like :class:`dict`, :class:`list`, and :class:`set` use internal locks |
| 81 |
to protect against concurrent modifications in ways that behave similarly to |
| 82 |
the GIL. However, Python has not historically guaranteed specific behavior for |
| 83 |
concurrent modifications to these built-in types, so this should be treated |
| 84 |
as a description of the current implementation, not a guarantee of current or |
| 85 |
future behavior. |
| 86 |
|
| 87 |
.. note:: |
| 88 |
|
| 89 |
It's recommended to use the :class:`threading.Lock` or other synchronization |
| 90 |
primitives instead of relying on the internal locks of built-in types, when |
| 91 |
possible. |
| 92 |
|
| 93 |
|
| 94 |
Known limitations |
| 95 |
================= |
| 96 |
|
| 97 |
This section describes known limitations of the free-threaded CPython build. |
| 98 |
|
| 99 |
Immortalization |
| 100 |
--------------- |
| 101 |
|
| 102 |
In the free-threaded build, some objects are :term:`immortal`. |
| 103 |
Immortal objects are not deallocated and have reference counts that are |
| 104 |
never modified. This is done to avoid reference count contention that would |
| 105 |
prevent efficient multi-threaded scaling. |
| 106 |
|
| 107 |
As of the 3.14 release, immortalization is limited to: |
| 108 |
|
| 109 |
* Code constants: numeric literals, string literals, and tuple literals |
| 110 |
composed of other constants. |
| 111 |
* Strings interned by :func:`sys.intern`. |
| 112 |
|
| 113 |
|
| 114 |
Frame objects |
| 115 |
------------- |
| 116 |
|
| 117 |
It is not safe to access :attr:`frame.f_locals` from a :ref:`frame <frame-objects>` |
| 118 |
object if that frame is currently executing in another thread, and doing so may |
| 119 |
crash the interpreter. |
| 120 |
|
| 121 |
|
| 122 |
Iterators |
| 123 |
--------- |
| 124 |
|
| 125 |
It is generally not thread-safe to access the same iterator object from |
| 126 |
multiple threads concurrently, and threads may see duplicate or missing |
| 127 |
elements. |
| 128 |
|
| 129 |
|
| 130 |
Single-threaded performance |
| 131 |
--------------------------- |
| 132 |
|
| 133 |
The free-threaded build has additional overhead when executing Python code |
| 134 |
compared to the default GIL-enabled build. The amount of overhead depends |
| 135 |
on the workload and hardware. On the pyperformance benchmark suite, the |
| 136 |
average overhead ranges from about 1% on macOS aarch64 to 8% on x86-64 Linux |
| 137 |
systems. |
| 138 |
|
| 139 |
|
| 140 |
Behavioral changes |
| 141 |
================== |
| 142 |
|
| 143 |
This section describes CPython behavioural changes with the free-threaded |
| 144 |
build. |
| 145 |
|
| 146 |
|
| 147 |
Context variables |
| 148 |
----------------- |
| 149 |
|
| 150 |
In the free-threaded build, the flag :data:`~sys.flags.thread_inherit_context` |
| 151 |
is set to true by default which causes threads created with |
| 152 |
:class:`threading.Thread` to start with a copy of the |
| 153 |
:class:`~contextvars.Context()` of the caller of |
| 154 |
:meth:`~threading.Thread.start`. In the default GIL-enabled build, the flag |
| 155 |
defaults to false so threads start with an |
| 156 |
empty :class:`~contextvars.Context()`. |
| 157 |
|
| 158 |
|
| 159 |
Warning filters |
| 160 |
--------------- |
| 161 |
|
| 162 |
In the free-threaded build, the flag :data:`~sys.flags.context_aware_warnings` |
| 163 |
is set to true by default. In the default GIL-enabled build, the flag defaults |
| 164 |
to false. If the flag is true then the :class:`warnings.catch_warnings` |
| 165 |
context manager uses a context variable for warning filters. If the flag is |
| 166 |
false then :class:`~warnings.catch_warnings` modifies the global filters list, |
| 167 |
which is not thread-safe. See the :mod:`warnings` module for more details. |