Skip to content

gh-142518: Improve mimalloc allocator docs#145224

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.

Sign up for GitHub

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
lysnikolaou merged 4 commits into from
Mar 11, 2026
Merged

gh-142518: Improve mimalloc allocator docs #145224

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
47f64cf
gh-142518: Improve mimalloc allocator docs
lysnikolaou Feb 25, 2026
de217b1
Address feedback
lysnikolaou Mar 10, 2026
8b45881
Fix table
lysnikolaou Mar 10, 2026
46fdbab
Address more feedback
lysnikolaou Mar 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 45 additions & 16 deletions Doc/c-api/memory.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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::

Expand All@@ -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
Expand DownExpand Up@@ -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::

Expand DownExpand Up@@ -420,23 +430,24 @@ 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:

* Name: value for :envvar:`PYTHONMALLOC` environment variable.
* ``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>`.
Expand DownExpand Up@@ -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
Comment thread
lysnikolaou marked this conversation as resolved.
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
=================
Expand Down
14 changes: 11 additions & 3 deletions Doc/using/cmdline.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -1074,6 +1074,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
Expand All@@ -1083,12 +1090,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)

@kumaraditya303kumaraditya303Mar 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On mimalloc I think it gets printed only at exit, I am not sure that even pymalloc prints it after each arena allocation

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.
Expand Down
3 changes: 3 additions & 0 deletions Doc/using/configure.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading