Skip to content

gh-119132: Remove "experimental" tag from the CPython free-threading. #135550

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 14 commits into from
Jun 16, 2025
Merged
4 changes: 2 additions & 2 deletions Doc/howto/free-threading-extensions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@
C API Extension Support for Free Threading
******************************************

Starting with the 3.13 release, CPython has experimental support for running
with the :term:`global interpreter lock` (GIL) disabled in a configuration
Starting with the 3.13 release, CPython has support for running with
the :term:`global interpreter lock` (GIL) disabled in a configuration
called :term:`free threading`. This document describes how to adapt C API
extensions to support free threading.

Expand Down
17 changes: 10 additions & 7 deletions Doc/howto/free-threading-python.rst
Original file line number Diff line number Diff line change
@@ -1,18 +1,21 @@
.. _freethreading-python-howto:

**********************************************
Python experimental support for free threading
**********************************************
*********************************
Python support for free threading
*********************************

Starting with the 3.13 release, CPython has experimental support for a build of
Starting with the 3.13 release, CPython has support for a build of
Python called :term:`free threading` where the :term:`global interpreter lock`
(GIL) is disabled. Free-threaded execution allows for full utilization of the
available processing power by running threads in parallel on available CPU cores.
While not all software will benefit from this automatically, programs
designed 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.
The free-threaded mode is working and continues to be improved, but
there is some additional overhead in single-threaded workloads compared
to the regular build. Additionally, third-party packages, in particular ones
with an :term:`extension module`, may not be ready for use in a
free-threaded build, and will re-enable the :term:`GIL`.

This document describes the implications of free threading
for Python code. See :ref:`freethreading-extensions-howto` for information on
Expand Down Expand Up @@ -43,7 +46,7 @@ Identifying free-threaded Python
================================

To check if the current interpreter supports free-threading, :option:`python -VV <-V>`
and :data:`sys.version` contain "experimental free-threading build".
and :data:`sys.version` contain "free-threading build".
The new :func:`sys._is_gil_enabled` function can be used to check whether
the GIL is actually disabled in the running process.

Expand Down
2 changes: 1 addition & 1 deletion Doc/library/ctypes.rst
Original file line number Diff line number Diff line change
Expand Up @@ -882,7 +882,7 @@ invalid non-\ ``NULL`` pointers would crash Python)::
Thread safety without the GIL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In Python 3.13, the :term:`GIL` may be disabled on :term:`experimental free threaded <free threading>` builds.
From Python 3.13 onward, the :term:`GIL` can be disabled on :term:`free threaded <free threading>` builds.
In ctypes, reads and writes to a single object concurrently is safe, but not across multiple objects:

.. code-block:: pycon
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/threading.rst
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ CPU-bound tasks, as only one thread can execute Python bytecode at a time.
Despite this, threads remain a useful tool for achieving concurrency in many
scenarios.

As of Python 3.13, experimental :term:`free-threaded <free threading>` builds
As of Python 3.13, :term:`free-threaded <free threading>` builds
can disable the GIL, enabling true parallel execution of threads, but this
feature is not available by default (see :pep:`703`).

Expand Down
4 changes: 2 additions & 2 deletions Doc/using/configure.rst
Original file line number Diff line number Diff line change
Expand Up @@ -290,8 +290,8 @@ General Options

.. option:: --disable-gil

Enables **experimental** support for running Python without the
:term:`global interpreter lock` (GIL): free threading build.
Enables support for running Python without the :term:`global interpreter
lock` (GIL): free threading build.

Defines the ``Py_GIL_DISABLED`` macro and adds ``"t"`` to
:data:`sys.abiflags`.
Expand Down
2 changes: 1 addition & 1 deletion Lib/platform.py
Original file line number Diff line number Diff line change
Expand Up @@ -1144,7 +1144,7 @@ def _sys_version(sys_version=None):
# CPython
cpython_sys_version_parser = re.compile(
r'([\w.+]+)\s*' # "version<space>"
r'(?:experimental free-threading build\s+)?' # "free-threading-build<space>"
r'(?:free-threading build\s+)?' # "free-threading-build<space>"
r'\(#?([^,]+)' # "(#buildno"
r'(?:,\s*([\w ]*)' # ", builddate"
r'(?:,\s*([\w :]*))?)?\)\s*' # ", buildtime)<space>"
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Remove "experimental" tag from the CPython free-threading build.
2 changes: 1 addition & 1 deletion PCbuild/build.bat
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ echo. -k Attempt to kill any running Pythons before building (usually done
echo. automatically by the pythoncore project)
echo. --pgo Build with Profile-Guided Optimization. This flag
echo. overrides -c and -d
echo. --disable-gil Enable experimental support for running without the GIL.
echo. --disable-gil Enable support for running without the GIL.
echo. --test-marker Enable the test marker within the build.
echo. --regen Regenerate all opcodes, grammar and tokens.
echo. --experimental-jit Enable the experimental just-in-time compiler.
Expand Down
2 changes: 1 addition & 1 deletion Python/getversion.c
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ void _Py_InitVersion(void)
}
initialized = 1;
#ifdef Py_GIL_DISABLED
const char *buildinfo_format = "%.80s experimental free-threading build (%.80s) %.80s";
const char *buildinfo_format = "%.80s free-threading build (%.80s) %.80s";
#else
const char *buildinfo_format = "%.80s (%.80s) %.80s";
#endif
Expand Down
4 changes: 2 additions & 2 deletions configure

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion configure.ac
Original file line number Diff line number Diff line change
Expand Up @@ -1716,7 +1716,7 @@ ABI_THREAD=""
# --disable-gil
AC_MSG_CHECKING([for --disable-gil])
AC_ARG_ENABLE([gil],
[AS_HELP_STRING([--disable-gil], [enable experimental support for running without the GIL (default is no)])],
[AS_HELP_STRING([--disable-gil], [enable support for running without the GIL (default is no)])],
[AS_VAR_IF([enable_gil], [yes], [disable_gil=no], [disable_gil=yes])], [disable_gil=no]
)
AC_MSG_RESULT([$disable_gil])
Expand Down
Loading