https://github.com/python/cpython/commit/7a1da4575b1d8fa87efb62334a8e99cd513d86e9
commit: 7a1da4575b1d8fa87efb62334a8e99cd513d86e9
branch: main
author: Lysandros Nikolaou <[email protected]>
committer: lysnikolaou <[email protected]>
date: 2026-03-11T15:14:47+01:00
summary:
gh-142518: Improve mimalloc allocator docs (#145224)
files:
M Doc/c-api/memory.rst
M Doc/using/cmdline.rst
M Doc/using/configure.rst
diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst
index 563c5d96b05362..9f84e4bc6dfd91 100644
--- a/Doc/c-api/memory.rst
+++ b/Doc/c-api/memory.rst
@@ -204,8 +204,11 @@ The following function sets, modeled after the ANSI C
standard, but specifying
behavior when requesting zero bytes, are available for allocating and releasing
memory from the Python heap.
-The :ref:`default memory allocator <default-memory-allocators>` uses the
-:ref:`pymalloc memory allocator <pymalloc>`.
+In the GIL-enabled build (default build) the
+:ref:`default memory allocator <default-memory-allocators>` uses the
+:ref:`pymalloc memory allocator <pymalloc>`, whereas in the
+:term:`free-threaded build`, the default is the
+:ref:`mimalloc memory allocator <mimalloc>` instead.
.. warning::
@@ -215,6 +218,11 @@ The :ref:`default memory allocator
<default-memory-allocators>` uses the
The default allocator is now pymalloc instead of system :c:func:`malloc`.
+.. versionchanged:: 3.13
+
+ In the :term:`free-threaded <free threading>` build, the default allocator
+ is now :ref:`mimalloc <mimalloc>`.
+
.. c:function:: void* PyMem_Malloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:expr:`void*` to the
@@ -340,7 +348,9 @@ memory from the Python heap.
the :ref:`Customize Memory Allocators <customize-memory-allocators>`
section.
The :ref:`default object allocator <default-memory-allocators>` uses the
-:ref:`pymalloc memory allocator <pymalloc>`.
+:ref:`pymalloc memory allocator <pymalloc>`. In the
+:term:`free-threaded <free threading>` build, the default is the
+:ref:`mimalloc memory allocator <mimalloc>` instead.
.. warning::
@@ -420,14 +430,16 @@ Default Memory Allocators
Default memory allocators:
-=============================== ==================== ==================
===================== ====================
-Configuration Name PyMem_RawMalloc
PyMem_Malloc PyObject_Malloc
-=============================== ==================== ==================
===================== ====================
-Release build ``"pymalloc"`` ``malloc``
``pymalloc`` ``pymalloc``
-Debug build ``"pymalloc_debug"`` ``malloc`` + debug
``pymalloc`` + debug ``pymalloc`` + debug
-Release build, without pymalloc ``"malloc"`` ``malloc``
``malloc`` ``malloc``
-Debug build, without pymalloc ``"malloc_debug"`` ``malloc`` + debug
``malloc`` + debug ``malloc`` + debug
-=============================== ==================== ==================
===================== ====================
+=================================== =======================
==================== ====================== ======================
+Configuration Name PyMem_RawMalloc
PyMem_Malloc PyObject_Malloc
+=================================== =======================
==================== ====================== ======================
+Release build ``"pymalloc"`` ``malloc``
``pymalloc`` ``pymalloc``
+Debug build ``"pymalloc_debug"`` ``malloc`` +
debug ``pymalloc`` + debug ``pymalloc`` + debug
+Release build, without pymalloc ``"malloc"`` ``malloc``
``malloc`` ``malloc``
+Debug build, without pymalloc ``"malloc_debug"`` ``malloc`` +
debug ``malloc`` + debug ``malloc`` + debug
+Free-threaded build ``"mimalloc"`` ``mimalloc``
``mimalloc`` ``mimalloc``
+Free-threaded debug build ``"mimalloc_debug"`` ``mimalloc`` +
debug ``mimalloc`` + debug ``mimalloc`` + debug
+=================================== =======================
==================== ====================== ======================
Legend:
@@ -435,8 +447,7 @@ Legend:
* ``malloc``: system allocators from the standard C library, C functions:
:c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`.
* ``pymalloc``: :ref:`pymalloc memory allocator <pymalloc>`.
-* ``mimalloc``: :ref:`mimalloc memory allocator <mimalloc>`. The pymalloc
- allocator will be used if mimalloc support isn't available.
+* ``mimalloc``: :ref:`mimalloc memory allocator <mimalloc>`.
* "+ debug": with :ref:`debug hooks on the Python memory allocators
<pymem-debug-hooks>`.
* "Debug build": :ref:`Python build in debug mode <debug-build>`.
@@ -733,9 +744,27 @@ The mimalloc allocator
.. versionadded:: 3.13
-Python supports the mimalloc allocator when the underlying platform support is
available.
-mimalloc "is a general purpose allocator with excellent performance
characteristics.
-Initially developed by Daan Leijen for the runtime systems of the Koka and
Lean languages."
+Python supports the `mimalloc <https://github.com/microsoft/mimalloc/>`__
+allocator when the underlying platform support is available.
+mimalloc is a general purpose allocator with excellent performance
+characteristics, initially developed by Daan Leijen for the runtime systems
+of the Koka and Lean languages.
+
+Unlike :ref:`pymalloc <pymalloc>`, which is optimized for small objects (512
+bytes or fewer), mimalloc handles allocations of any size.
+
+In the :term:`free-threaded <free threading>` build, mimalloc is the default
+and **required** allocator for the :c:macro:`PYMEM_DOMAIN_MEM` and
+:c:macro:`PYMEM_DOMAIN_OBJ` domains. It cannot be disabled in free-threaded
+builds. The free-threaded build uses per-thread mimalloc heaps, which allows
+allocation and deallocation to proceed without locking in most cases.
+
+In the default (non-free-threaded) build, mimalloc is available but not the
+default allocator. It can be selected at runtime using
+:envvar:`PYTHONMALLOC`\ ``=mimalloc`` (or ``mimalloc_debug`` to include
+:ref:`debug hooks <pymem-debug-hooks>`). It can be disabled at build time
+using the :option:`--without-mimalloc` configure option, but this option
+cannot be combined with :option:`--disable-gil`.
tracemalloc C API
=================
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 5c3d44395c0039..ce6872f3c0fda3 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -1085,6 +1085,13 @@ conflict.
* ``pymalloc_debug``: same as ``pymalloc`` but also install debug hooks.
* ``mimalloc_debug``: same as ``mimalloc`` but also install debug hooks.
+ .. note::
+
+ In the :term:`free-threaded <free threading>` build, the ``malloc``,
+ ``malloc_debug``, ``pymalloc``, and ``pymalloc_debug`` values are not
+ supported. Only ``default``, ``debug``, ``mimalloc``, and
+ ``mimalloc_debug`` are accepted.
+
.. versionadded:: 3.6
.. versionchanged:: 3.7
@@ -1094,12 +1101,13 @@ conflict.
.. envvar:: PYTHONMALLOCSTATS
If set to a non-empty string, Python will print statistics of the
- :ref:`pymalloc memory allocator <pymalloc>` every time a new pymalloc object
- arena is created, and on shutdown.
+ :ref:`pymalloc memory allocator <pymalloc>` or the
+ :ref:`mimalloc memory allocator <mimalloc>` (whichever is in use)
+ every time a new object arena is created, and on shutdown.
This variable is ignored if the :envvar:`PYTHONMALLOC` environment variable
is used to force the :c:func:`malloc` allocator of the C library, or if
- Python is configured without ``pymalloc`` support.
+ Python is configured without both ``pymalloc`` and ``mimalloc`` support.
.. versionchanged:: 3.6
This variable can now also be used on Python compiled in release mode.
diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst
index 813127663ed8fe..6bef290d181fc9 100644
--- a/Doc/using/configure.rst
+++ b/Doc/using/configure.rst
@@ -774,6 +774,9 @@ also be used to improve performance.
Disable the fast :ref:`mimalloc <mimalloc>` allocator
(enabled by default).
+ This option cannot be used together with :option:`--disable-gil`
+ because the :term:`free-threaded <free threading>` build requires mimalloc.
+
See also :envvar:`PYTHONMALLOC` environment variable.
.. option:: --without-pymalloc
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
