What does the PYTHONMALLOC environment variable control in CPython?

### What the variable selects `PYTHONMALLOC` is read during interpreter pre-initialisation, before any Python code runs, and it chooses which allocator CPython installs and whether the debug hooks are wrapped around it. The values on CPython 3.14's standard build: * `default` — the built-in choice: pymalloc for objects, the system allocator for raw memory. * `pymalloc` — the small-object allocator explicitly. * `malloc` — route **everything** to the C library's `malloc`, including the sub-512-byte requests pymalloc would normally serve. * `pymalloc_debug`, `malloc_debug` — the same two, with debug hooks installed. * `debug` — the default allocators plus debug hooks. The free-threaded build (experimental in 3.13, officially supported in 3.14) uses **mimalloc** as its object allocator and accepts the corresponding mimalloc values there. An unrecognised value is fatal: the interpreter aborts during pre-initialisation with "PYTHONMALLOC: unknown allocator" rather than falling back silently. ### Why anyone sets it **`PYTHONMALLOC=malloc` makes external C memory tooling usable.** A native leak detector or bounds checker instruments `malloc`/`free`. With pymalloc in the way, thousands of Python objects share one 1 MiB arena that the tool sees as a single allocation, so an overrun from one object into its neighbour is invisible and every real allocation site is hidden behind the arena. Routing every request through `malloc` gives the tool one allocation per object, at a large speed cost — this is a debugging configuration, never a production one. **The debug hooks catch C-extension memory bugs from inside CPython.** They fill freshly allocated memory with a recognisable byte pattern (so use-before-initialise shows up), write guard bytes before and after each block to detect buffer overruns and underruns, fill freed memory with a different pattern to expose use-after-free, and check that memory allocated in one allocator domain is released in the same one. They abort with a diagnostic at the point of detection instead of leaving corruption to surface somewhere unrelated hours later. `-X dev` (development mode) turns the same hooks on without setting the variable, and `PYTHONDEVMODE=1` is its environment equivalent. ### The companion variable `PYTHONMALLOCSTATS=1` makes CPython dump the pymalloc statistics — the size-class table plus the arena summary — every time a new arena is created and again at shutdown. It is the non-interactive sibling of calling `sys._debugmallocstats()` yourself, and it only has anything to say while pymalloc is actually the allocator in use. ```console PYTHONMALLOC=malloc python3 -c "import sys; print(sys.getallocatedblocks())" ``` ### The observable side effects worth knowing Switching away from pymalloc changes what the introspection tools report, which surprises people mid-investigation: * `sys.getallocatedblocks()` returns **0** under `PYTHONMALLOC=malloc` — it counts pymalloc blocks, and there are none. * `sys._debugmallocstats()` still runs but prints only the object free-list section; the size-class table and arena counts are gone, because there are no pools or arenas. * RSS behaviour changes too: the arena-occupancy effect disappears and retention becomes entirely the system allocator's business, so a memory profile measured under `malloc` does not predict production behaviour under the default build. ### How to talk about it The useful framing is that `PYTHONMALLOC` is a **diagnostic switch, not a tuning knob**. There is no production workload where turning pymalloc off is the answer to a performance or memory problem — small-object allocation gets slower and the fragmentation story does not improve, it just moves to another allocator. You reach for it when a C extension or embedding is corrupting memory and you need either CPython's own guard bytes or an external checker's view, and you turn it off again as soon as the bug is found.