646 lines
40 KiB
HTML
646 lines
40 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en" data-content_root="../">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
<meta property="og:title" content="Python support for free threading" />
|
||
<meta property="og:type" content="website" />
|
||
<meta property="og:url" content="https://docs.python.org/3/howto/free-threading-python.html" />
|
||
<meta property="og:site_name" content="Python documentation" />
|
||
<meta property="og:description" content="Starting with the 3.13 release, CPython has support for a build of Python called free threading where the global interpreter lock(GIL) is disabled. Free-threaded execution allows for full utilizati..." />
|
||
<meta property="og:image" content="_static/og-image.png" />
|
||
<meta property="og:image:alt" content="Python documentation" />
|
||
<meta name="description" content="Starting with the 3.13 release, CPython has support for a build of Python called free threading where the global interpreter lock(GIL) is disabled. Free-threaded execution allows for full utilizati..." />
|
||
<meta name="theme-color" content="#3776ab">
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
|
||
<title>Python support for free threading — Python 3.15.0 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=48df1187" />
|
||
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
|
||
|
||
<script src="../_static/documentation_options.js?v=0fe728b1"></script>
|
||
<script src="../_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.15.0 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="C API Extension Support for Free Threading" href="free-threading-extensions.html" />
|
||
<link rel="prev" title="The Python 2.3 Method Resolution Order" href="mro.html" />
|
||
|
||
|
||
<link rel="canonical" href="https://docs.python.org/3/howto/free-threading-python.html">
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg">
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
<script type="text/javascript" src="../_static/search-focus.js"></script>
|
||
<script type="text/javascript" src="../_static/themetoggle.js"></script>
|
||
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
|
||
<meta name="readthedocs-addons-api-version" content="1">
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
|
||
<nav class="nav-content" role="navigation">
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<span class="nav-items-wrapper">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Python logo">
|
||
</a>
|
||
<span class="version_switcher_placeholder"></span>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
|
||
</svg>
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
|
||
<input type="submit" value="Go">
|
||
</form>
|
||
</span>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label>
|
||
<div>
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">Python support for free threading</a><ul>
|
||
<li><a class="reference internal" href="#installation">Installation</a></li>
|
||
<li><a class="reference internal" href="#identifying-free-threaded-python">Identifying free-threaded Python</a></li>
|
||
<li><a class="reference internal" href="#the-global-interpreter-lock-in-free-threaded-python">The global interpreter lock in free-threaded Python</a></li>
|
||
<li><a class="reference internal" href="#thread-safety">Thread safety</a></li>
|
||
<li><a class="reference internal" href="#known-limitations">Known limitations</a><ul>
|
||
<li><a class="reference internal" href="#immortalization">Immortalization</a></li>
|
||
<li><a class="reference internal" href="#frame-objects">Frame objects</a></li>
|
||
<li><a class="reference internal" href="#iterators">Iterators</a></li>
|
||
<li><a class="reference internal" href="#single-threaded-performance">Single-threaded performance</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#behavioral-changes">Behavioral changes</a><ul>
|
||
<li><a class="reference internal" href="#context-variables">Context variables</a></li>
|
||
<li><a class="reference internal" href="#warning-filters">Warning filters</a></li>
|
||
<li><a class="reference internal" href="#increased-memory-usage">Increased memory usage</a><ul>
|
||
<li><a class="reference internal" href="#all-interned-strings-are-immortal">All interned strings are immortal</a></li>
|
||
<li><a class="reference internal" href="#non-gc-objects-have-a-larger-object-header">Non-GC objects have a larger object header</a></li>
|
||
<li><a class="reference internal" href="#qsbr-can-delay-freeing-of-memory">QSBR can delay freeing of memory</a></li>
|
||
<li><a class="reference internal" href="#mimalloc-allocator-vs-pymalloc">mimalloc allocator vs pymalloc</a></li>
|
||
<li><a class="reference internal" href="#free-threaded-reference-counting-can-cause-objects-to-live-longer">Free-threaded reference counting can cause objects to live longer</a></li>
|
||
<li><a class="reference internal" href="#per-thread-reference-counting-can-delay-freeing-objects">Per-thread reference counting can delay freeing objects</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="mro.html"
|
||
title="previous chapter">The Python 2.3 Method Resolution Order</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="free-threading-extensions.html"
|
||
title="next chapter">C API Extension Support for Free Threading</a></p>
|
||
</div>
|
||
<script>
|
||
document.addEventListener('DOMContentLoaded', () => {
|
||
const title = document.querySelector('meta[property="og:title"]').content;
|
||
const elements = document.querySelectorAll('.improvepage');
|
||
const pageurl = window.location.href.split('?')[0];
|
||
elements.forEach(element => {
|
||
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
|
||
url.searchParams.set('pagetitle', title);
|
||
url.searchParams.set('pageurl', pageurl);
|
||
url.searchParams.set('pagesource', "howto/free-threading-python.rst");
|
||
element.href = url.toString();
|
||
});
|
||
});
|
||
</script>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a bug</a></li>
|
||
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.15/Doc/howto/free-threading-python.rst?plain=1"
|
||
rel="nofollow">Show source
|
||
</a>
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="free-threading-extensions.html" title="C API Extension Support for Free Threading"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="mro.html" title="The Python 2.3 Method Resolution Order"
|
||
accesskey="P">previous</a> |</li>
|
||
|
||
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.15.0 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python HOWTOs</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Python support for free threading</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
|
||
<input type="submit" value="Go">
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="python-support-for-free-threading">
|
||
<span id="freethreading-python-howto"></span><h1>Python support for free threading<a class="headerlink" href="#python-support-for-free-threading" title="Link to this heading">¶</a></h1>
|
||
<p>Starting with the 3.13 release, CPython has support for a build of
|
||
Python called <a class="reference internal" href="../glossary.html#term-free-threading"><span class="xref std std-term">free threading</span></a> where the <a class="reference internal" href="../glossary.html#term-global-interpreter-lock"><span class="xref std std-term">global interpreter lock</span></a>
|
||
(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.</p>
|
||
<p>Some third-party packages, in particular ones
|
||
with an <a class="reference internal" href="../glossary.html#term-extension-module"><span class="xref std std-term">extension module</span></a>, may not be ready for use in a
|
||
free-threaded build, and will re-enable the <a class="reference internal" href="../glossary.html#term-GIL"><span class="xref std std-term">GIL</span></a>.</p>
|
||
<p>This document describes the implications of free threading
|
||
for Python code. See <a class="reference internal" href="free-threading-extensions.html#freethreading-extensions-howto"><span class="std std-ref">C API Extension Support for Free Threading</span></a> for information on
|
||
how to write C extensions that support the free-threaded build.</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p><span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0703/"><strong>PEP 703</strong></a> – Making the Global Interpreter Lock Optional in CPython for an
|
||
overall description of free-threaded Python.</p>
|
||
</div>
|
||
<section id="installation">
|
||
<h2>Installation<a class="headerlink" href="#installation" title="Link to this heading">¶</a></h2>
|
||
<p>Starting with Python 3.13, the official macOS and Windows installers
|
||
optionally support installing free-threaded Python binaries. The installers
|
||
are available at <a class="reference external" href="https://www.python.org/downloads/">https://www.python.org/downloads/</a>.</p>
|
||
<p>For information on other platforms, see the <a class="reference external" href="https://py-free-threading.github.io/installing-cpython/">Installing a Free-Threaded Python</a>, a
|
||
community-maintained installation guide for installing free-threaded Python.</p>
|
||
<p>When building CPython from source, the <a class="reference internal" href="../using/configure.html#cmdoption-disable-gil"><code class="xref std std-option docutils literal notranslate"><span class="pre">--disable-gil</span></code></a> configure option
|
||
should be used to build a free-threaded Python interpreter.</p>
|
||
</section>
|
||
<section id="identifying-free-threaded-python">
|
||
<h2>Identifying free-threaded Python<a class="headerlink" href="#identifying-free-threaded-python" title="Link to this heading">¶</a></h2>
|
||
<p>To check if the current interpreter supports free-threading, <a class="reference internal" href="../using/cmdline.html#cmdoption-V"><code class="xref std std-option docutils literal notranslate"><span class="pre">python</span> <span class="pre">-VV</span></code></a>
|
||
and <a class="reference internal" href="../library/sys.html#sys.version" title="sys.version"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.version</span></code></a> contain “free-threading build”.
|
||
The new <a class="reference internal" href="../library/sys.html#sys._is_gil_enabled" title="sys._is_gil_enabled"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys._is_gil_enabled()</span></code></a> function can be used to check whether
|
||
the GIL is actually disabled in the running process.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">sysconfig.get_config_var("Py_GIL_DISABLED")</span></code> configuration variable can
|
||
be used to determine whether the build supports free threading. If the variable
|
||
is set to <code class="docutils literal notranslate"><span class="pre">1</span></code>, then the build supports free threading. This is the recommended
|
||
mechanism for decisions related to the build configuration.</p>
|
||
</section>
|
||
<section id="the-global-interpreter-lock-in-free-threaded-python">
|
||
<h2>The global interpreter lock in free-threaded Python<a class="headerlink" href="#the-global-interpreter-lock-in-free-threaded-python" title="Link to this heading">¶</a></h2>
|
||
<p>Free-threaded builds of CPython support optionally running with the GIL enabled
|
||
at runtime using the environment variable <span class="target" id="index-1"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHON_GIL"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHON_GIL</span></code></a> or
|
||
the command-line option <a class="reference internal" href="../using/cmdline.html#cmdoption-X"><code class="xref std std-option docutils literal notranslate"><span class="pre">-X</span> <span class="pre">gil</span></code></a>.</p>
|
||
<p>The GIL may also automatically be enabled when importing a C-API extension
|
||
module that is not explicitly marked as supporting free threading. A warning
|
||
will be printed in this case.</p>
|
||
<p>In addition to individual package documentation, the following websites track
|
||
the status of popular packages support for free threading:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference external" href="https://py-free-threading.github.io/tracking/">https://py-free-threading.github.io/tracking/</a></p></li>
|
||
<li><p><a class="reference external" href="https://hugovk.github.io/free-threaded-wheels/">https://hugovk.github.io/free-threaded-wheels/</a></p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="thread-safety">
|
||
<h2>Thread safety<a class="headerlink" href="#thread-safety" title="Link to this heading">¶</a></h2>
|
||
<p>The free-threaded build of CPython aims to provide similar thread-safety
|
||
behavior at the Python level to the default GIL-enabled build. Built-in
|
||
types like <a class="reference internal" href="../builtins/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>, <a class="reference internal" href="../builtins/stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>, and <a class="reference internal" href="../builtins/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> use internal locks
|
||
to protect against concurrent modifications in ways that behave similarly to
|
||
the GIL. See <a class="reference internal" href="../builtins/threadsafety.html#threadsafety"><span class="std std-ref">Thread Safety Guarantees</span></a> for the guarantees provided by built-in types.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>It’s recommended to use the <a class="reference internal" href="../library/threading.html#threading.Lock" title="threading.Lock"><code class="xref py py-class docutils literal notranslate"><span class="pre">threading.Lock</span></code></a> or other synchronization
|
||
primitives instead of relying on the internal locks of built-in types, when
|
||
possible.</p>
|
||
</div>
|
||
</section>
|
||
<section id="known-limitations">
|
||
<h2>Known limitations<a class="headerlink" href="#known-limitations" title="Link to this heading">¶</a></h2>
|
||
<p>This section describes known limitations of the free-threaded CPython build.</p>
|
||
<section id="immortalization">
|
||
<h3>Immortalization<a class="headerlink" href="#immortalization" title="Link to this heading">¶</a></h3>
|
||
<p>In the free-threaded build, some objects are <a class="reference internal" href="../glossary.html#term-immortal"><span class="xref std std-term">immortal</span></a>.
|
||
Immortal objects are not deallocated and have reference counts that are
|
||
never modified. This is done to avoid reference count contention that would
|
||
prevent efficient multi-threaded scaling.</p>
|
||
<p>As of the 3.14 release, immortalization is limited to:</p>
|
||
<ul class="simple">
|
||
<li><p>Code constants: numeric literals, string literals, and tuple literals
|
||
composed of other constants.</p></li>
|
||
<li><p>Strings interned by <a class="reference internal" href="../library/sys.html#sys.intern" title="sys.intern"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.intern()</span></code></a>.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="frame-objects">
|
||
<h3>Frame objects<a class="headerlink" href="#frame-objects" title="Link to this heading">¶</a></h3>
|
||
<p>It is not safe to access <a class="reference internal" href="../reference/datamodel.html#frame.f_locals" title="frame.f_locals"><code class="xref py py-attr docutils literal notranslate"><span class="pre">frame.f_locals</span></code></a> from a <a class="reference internal" href="../reference/datamodel.html#frame-objects"><span class="std std-ref">frame</span></a>
|
||
object if that frame is currently executing in another thread, and doing so may
|
||
crash the interpreter.</p>
|
||
</section>
|
||
<section id="iterators">
|
||
<h3>Iterators<a class="headerlink" href="#iterators" title="Link to this heading">¶</a></h3>
|
||
<p>It is generally not thread-safe to access the same iterator object from
|
||
multiple threads concurrently, and threads may see duplicate or missing
|
||
elements.</p>
|
||
</section>
|
||
<section id="single-threaded-performance">
|
||
<h3>Single-threaded performance<a class="headerlink" href="#single-threaded-performance" title="Link to this heading">¶</a></h3>
|
||
<p>The free-threaded build has additional overhead when executing Python code
|
||
compared to the default GIL-enabled build. The amount of overhead depends
|
||
on the workload and hardware. On the pyperformance benchmark suite, the
|
||
average overhead ranges from about 1% on macOS aarch64 to 8% on x86-64 Linux
|
||
systems.</p>
|
||
</section>
|
||
</section>
|
||
<section id="behavioral-changes">
|
||
<h2>Behavioral changes<a class="headerlink" href="#behavioral-changes" title="Link to this heading">¶</a></h2>
|
||
<p>This section describes CPython behavioural changes with the free-threaded
|
||
build.</p>
|
||
<section id="context-variables">
|
||
<h3>Context variables<a class="headerlink" href="#context-variables" title="Link to this heading">¶</a></h3>
|
||
<p>In the free-threaded build, the flag <a class="reference internal" href="../library/sys.html#sys.flags.thread_inherit_context" title="sys.flags.thread_inherit_context"><code class="xref py py-data docutils literal notranslate"><span class="pre">thread_inherit_context</span></code></a>
|
||
is set to true by default which causes threads created with
|
||
<a class="reference internal" href="../library/threading.html#threading.Thread" title="threading.Thread"><code class="xref py py-class docutils literal notranslate"><span class="pre">threading.Thread</span></code></a> to start with a copy of the
|
||
<a class="reference internal" href="../library/contextvars.html#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context()</span></code></a> of the caller of
|
||
<a class="reference internal" href="../library/threading.html#threading.Thread.start" title="threading.Thread.start"><code class="xref py py-meth docutils literal notranslate"><span class="pre">start()</span></code></a>. In the default GIL-enabled build, the flag
|
||
defaults to false so threads start with an
|
||
empty <code class="xref py py-class docutils literal notranslate"><span class="pre">Context()</span></code>.</p>
|
||
</section>
|
||
<section id="warning-filters">
|
||
<h3>Warning filters<a class="headerlink" href="#warning-filters" title="Link to this heading">¶</a></h3>
|
||
<p>In the free-threaded build, the flag <a class="reference internal" href="../library/sys.html#sys.flags.context_aware_warnings" title="sys.flags.context_aware_warnings"><code class="xref py py-data docutils literal notranslate"><span class="pre">context_aware_warnings</span></code></a>
|
||
is set to true by default. In the default GIL-enabled build, the flag defaults
|
||
to false. If the flag is true then the <a class="reference internal" href="../library/warnings.html#warnings.catch_warnings" title="warnings.catch_warnings"><code class="xref py py-class docutils literal notranslate"><span class="pre">warnings.catch_warnings</span></code></a>
|
||
context manager uses a context variable for warning filters. If the flag is
|
||
false then <code class="xref py py-class docutils literal notranslate"><span class="pre">catch_warnings</span></code> modifies the global filters list,
|
||
which is not thread-safe. See the <a class="reference internal" href="../library/warnings.html#module-warnings" title="warnings: Issue warning messages and control their disposition."><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code></a> module for more details.</p>
|
||
</section>
|
||
<section id="increased-memory-usage">
|
||
<h3>Increased memory usage<a class="headerlink" href="#increased-memory-usage" title="Link to this heading">¶</a></h3>
|
||
<p>The free-threaded build will typically use more memory compared to the default
|
||
build. There are multiple reasons for this, mostly due to design decisions.</p>
|
||
<section id="all-interned-strings-are-immortal">
|
||
<h4>All interned strings are immortal<a class="headerlink" href="#all-interned-strings-are-immortal" title="Link to this heading">¶</a></h4>
|
||
<p>For modern Python versions (since version 2.3), interning a string (e.g. with
|
||
<a class="reference internal" href="../library/sys.html#sys.intern" title="sys.intern"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.intern()</span></code></a>) does not cause it to become immortal. Instead, if the last
|
||
reference to that string disappears, it will be removed from the interned
|
||
string table. This is not the case for the free-threaded build and any interned
|
||
string will become immortal, surviving until interpreter shutdown.</p>
|
||
</section>
|
||
<section id="non-gc-objects-have-a-larger-object-header">
|
||
<h4>Non-GC objects have a larger object header<a class="headerlink" href="#non-gc-objects-have-a-larger-object-header" title="Link to this heading">¶</a></h4>
|
||
<p>The free-threaded build uses a different <a class="reference internal" href="../c-api/structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> structure. Instead
|
||
of having the GC related information allocated before the <code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code>
|
||
structure, like in the default build, the GC related info is part of the normal
|
||
object header. For example, on the AMD64 platform, <code class="docutils literal notranslate"><span class="pre">None</span></code> uses 32 bytes on
|
||
the free-threaded build vs 16 bytes for the default build. GC objects (such as
|
||
dicts and lists) are the same size for both builds since the free-threaded
|
||
build does not use additional space for the GC info.</p>
|
||
</section>
|
||
<section id="qsbr-can-delay-freeing-of-memory">
|
||
<h4>QSBR can delay freeing of memory<a class="headerlink" href="#qsbr-can-delay-freeing-of-memory" title="Link to this heading">¶</a></h4>
|
||
<p>In order to safely implement lock-free data structures, a safe memory
|
||
reclamation (SMR) scheme is used, known as quiescent state-based reclamation
|
||
(QSBR). This means that the memory backing data structures allowing lock-free
|
||
access will use QSBR, which defers the free operation, rather than immediately
|
||
freeing the memory. Two examples of these data structures are the list object
|
||
and the dictionary keys object. See <code class="docutils literal notranslate"><span class="pre">InternalDocs/qsbr.md</span></code> in the CPython
|
||
source tree for more details on how QSBR is implemented. Running
|
||
<a class="reference internal" href="../library/gc.html#gc.collect" title="gc.collect"><code class="xref py py-func docutils literal notranslate"><span class="pre">gc.collect()</span></code></a> should cause all memory being held by QSBR to be actually
|
||
freed. Note that even when QSBR frees the memory, the underlying memory
|
||
allocator may not immediately return that memory to the OS and so the resident
|
||
set size (RSS) of the process might not decrease.</p>
|
||
</section>
|
||
<section id="mimalloc-allocator-vs-pymalloc">
|
||
<h4>mimalloc allocator vs pymalloc<a class="headerlink" href="#mimalloc-allocator-vs-pymalloc" title="Link to this heading">¶</a></h4>
|
||
<p>The default build will normally use the “pymalloc” memory allocator for small
|
||
allocations (512 bytes or smaller). The free-threaded build does not use
|
||
pymalloc and allocates all Python objects using the “mimalloc” allocator. The
|
||
pymalloc allocator has the following properties that help keep memory usage
|
||
low: small per-allocated-block overhead, effective memory fragmentation
|
||
prevention, and quick return of free memory to the operating system. The
|
||
mimalloc allocator does quite well in these respects as well but can have some
|
||
more overhead.</p>
|
||
<p>In the free-threaded build, mimalloc manages memory in a number of separate
|
||
heaps (currently four). For example, all GC supporting objects are allocated
|
||
from their own heap. Using separate heaps means that free memory in one heap
|
||
cannot be used for an allocation that uses another heap. Also, some heaps are
|
||
configured to use QSBR (quiescent-state based reclamation) when freeing the
|
||
memory that backs up the heap (known as “pages” in mimalloc terminology). The
|
||
use of QSBR creates a delay between all memory blocks for a page being freed
|
||
and the memory page being released, either for new allocations or back to the
|
||
OS.</p>
|
||
<p>The mimalloc allocator also defers returning freed memory back to the OS. You
|
||
can reduce that delay by setting the environment variable
|
||
<code class="xref std std-envvar docutils literal notranslate"><span class="pre">MIMALLOC_PURGE_DELAY</span></code> to <code class="docutils literal notranslate"><span class="pre">0</span></code>. Note that this will likely reduce
|
||
the performance of the allocator.</p>
|
||
</section>
|
||
<section id="free-threaded-reference-counting-can-cause-objects-to-live-longer">
|
||
<h4>Free-threaded reference counting can cause objects to live longer<a class="headerlink" href="#free-threaded-reference-counting-can-cause-objects-to-live-longer" title="Link to this heading">¶</a></h4>
|
||
<p>In the default build, when an object’s reference count reaches zero, it is
|
||
normally deallocated. The free-threaded build uses “biased reference
|
||
counting”, with a fast-path for objects “owned” by the current thread and a
|
||
slow path for other objects. See <span class="target" id="index-2"></span><a class="pep reference external" href="https://peps.python.org/pep-0703/"><strong>PEP 703</strong></a> for additional details. Any time
|
||
an object’s reference count ends up in a “queued” state, deallocation can be
|
||
deferred. The queued state is cleared from the “eval breaker” section of the
|
||
bytecode evaluator.</p>
|
||
<p>The free-threaded build also allows a different mode of reference counting,
|
||
known as “deferred reference counting”. This mode is enabled by setting a flag
|
||
on a per-object basis. Deferred reference counting is enabled for the
|
||
following types:</p>
|
||
<ul class="simple">
|
||
<li><p>module objects</p></li>
|
||
<li><p>module top-level functions</p></li>
|
||
<li><p>class methods defined in the class scope</p></li>
|
||
<li><p>descriptor objects</p></li>
|
||
<li><p>thread-local objects, created by <a class="reference internal" href="../library/threading.html#threading.local" title="threading.local"><code class="xref py py-class docutils literal notranslate"><span class="pre">threading.local</span></code></a></p></li>
|
||
</ul>
|
||
<p>When deferred reference counting is enabled, references from Python function
|
||
stacks are not added to the reference count. This scheme reduces the overhead
|
||
of reference counting, especially for objects used from multiple threads.
|
||
Because the stack references are not counted, objects with deferred reference
|
||
counting are not immediately freed when their internal reference count goes to
|
||
zero. Instead, they are examined by the next GC run and, if no stack
|
||
references to them are found, they are freed. This means these objects are
|
||
freed by the GC and not when their reference count goes to zero, as is typical.</p>
|
||
</section>
|
||
<section id="per-thread-reference-counting-can-delay-freeing-objects">
|
||
<h4>Per-thread reference counting can delay freeing objects<a class="headerlink" href="#per-thread-reference-counting-can-delay-freeing-objects" title="Link to this heading">¶</a></h4>
|
||
<p>To avoid contention on the reference count fields of frequently shared
|
||
objects, the free-threaded build also uses “per-thread reference counting”
|
||
for a few selected object types. Rather than updating a single shared
|
||
reference count, each thread maintains its own local reference count array,
|
||
indexed by a unique id assigned to the object. The true reference count is
|
||
only computed by summing the per-thread counts when the object’s local
|
||
count drops to zero. Per-thread reference counting is currently used for:</p>
|
||
<ul class="simple">
|
||
<li><p>heap type objects (classes created in Python)</p></li>
|
||
<li><p>code objects</p></li>
|
||
<li><p>the <code class="docutils literal notranslate"><span class="pre">__dict__</span></code> of module objects</p></li>
|
||
</ul>
|
||
<p>Because the per-thread counts must be merged back to the object before it
|
||
can be deallocated, objects using per-thread reference counting are
|
||
typically freed later than they would be in the default build. In
|
||
particular, such an object is usually not freed until the thread that
|
||
referenced it reaches a safe point (for example, in the “eval breaker”
|
||
section of the bytecode evaluator) or exits. Running <a class="reference internal" href="../library/gc.html#gc.collect" title="gc.collect"><code class="xref py py-func docutils literal notranslate"><span class="pre">gc.collect()</span></code></a>
|
||
will merge the per-thread counts and allow these objects to be freed.</p>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="Main">
|
||
<div class="sphinxsidebarwrapper">
|
||
<div>
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">Python support for free threading</a><ul>
|
||
<li><a class="reference internal" href="#installation">Installation</a></li>
|
||
<li><a class="reference internal" href="#identifying-free-threaded-python">Identifying free-threaded Python</a></li>
|
||
<li><a class="reference internal" href="#the-global-interpreter-lock-in-free-threaded-python">The global interpreter lock in free-threaded Python</a></li>
|
||
<li><a class="reference internal" href="#thread-safety">Thread safety</a></li>
|
||
<li><a class="reference internal" href="#known-limitations">Known limitations</a><ul>
|
||
<li><a class="reference internal" href="#immortalization">Immortalization</a></li>
|
||
<li><a class="reference internal" href="#frame-objects">Frame objects</a></li>
|
||
<li><a class="reference internal" href="#iterators">Iterators</a></li>
|
||
<li><a class="reference internal" href="#single-threaded-performance">Single-threaded performance</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#behavioral-changes">Behavioral changes</a><ul>
|
||
<li><a class="reference internal" href="#context-variables">Context variables</a></li>
|
||
<li><a class="reference internal" href="#warning-filters">Warning filters</a></li>
|
||
<li><a class="reference internal" href="#increased-memory-usage">Increased memory usage</a><ul>
|
||
<li><a class="reference internal" href="#all-interned-strings-are-immortal">All interned strings are immortal</a></li>
|
||
<li><a class="reference internal" href="#non-gc-objects-have-a-larger-object-header">Non-GC objects have a larger object header</a></li>
|
||
<li><a class="reference internal" href="#qsbr-can-delay-freeing-of-memory">QSBR can delay freeing of memory</a></li>
|
||
<li><a class="reference internal" href="#mimalloc-allocator-vs-pymalloc">mimalloc allocator vs pymalloc</a></li>
|
||
<li><a class="reference internal" href="#free-threaded-reference-counting-can-cause-objects-to-live-longer">Free-threaded reference counting can cause objects to live longer</a></li>
|
||
<li><a class="reference internal" href="#per-thread-reference-counting-can-delay-freeing-objects">Per-thread reference counting can delay freeing objects</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="mro.html"
|
||
title="previous chapter">The Python 2.3 Method Resolution Order</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="free-threading-extensions.html"
|
||
title="next chapter">C API Extension Support for Free Threading</a></p>
|
||
</div>
|
||
<script>
|
||
document.addEventListener('DOMContentLoaded', () => {
|
||
const title = document.querySelector('meta[property="og:title"]').content;
|
||
const elements = document.querySelectorAll('.improvepage');
|
||
const pageurl = window.location.href.split('?')[0];
|
||
elements.forEach(element => {
|
||
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
|
||
url.searchParams.set('pagetitle', title);
|
||
url.searchParams.set('pageurl', pageurl);
|
||
url.searchParams.set('pagesource', "howto/free-threading-python.rst");
|
||
element.href = url.toString();
|
||
});
|
||
});
|
||
</script>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a bug</a></li>
|
||
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.15/Doc/howto/free-threading-python.rst?plain=1"
|
||
rel="nofollow">Show source
|
||
</a>
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div id="sidebarbutton" title="Collapse sidebar">
|
||
<span>«</span>
|
||
</div>
|
||
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="free-threading-extensions.html" title="C API Extension Support for Free Threading"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="mro.html" title="The Python 2.3 Method Resolution Order"
|
||
>previous</a> |</li>
|
||
|
||
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.15.0 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python HOWTOs</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Python support for free threading</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
|
||
<input type="submit" value="Go">
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.
|
||
<br>
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br>
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br>
|
||
|
||
See <a href="/license.html">History and License</a> for more information.<br>
|
||
|
||
|
||
<br>
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br>
|
||
<br>
|
||
Last updated on Oct 09, 2026 (11:35 UTC).
|
||
|
||
<a href="/bugs.html">Found a bug</a>?
|
||
|
||
<br>
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |