Text of peps.python.org › pep-0831 as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 831 – Frame Pointers Everywhere: Enabling System-Level Observability for Python | peps.python.org

PEP 831 – Frame Pointers Everywhere: Enabling System-Level Observability for Python PEP 831 – Frame Pointers Everywhere: Enabling System-Level Observability for Python Author : Pablo Galindo Salgado <pablogsal at python.org>, Ken Jin <kenjin at python.org>, Savannah Ostrowski <savannah at python.org>, Diego Russo <diego.russo at arm.com> Discussions-To : Discourse thread Status : Final Type : Standards Track Created : 14-Mar-2026 Python-Version : 3.15 Post-History : 13-Apr-2026 Resolution : 30-Apr-2026 Table of Contents Abstract Motivation What Are Frame Pointers?

Profilers Are Slower and Less Accurate Without Frame Pointers Debuggers Benefit from Frame Pointers The Kernel’s Stack Unwinder Only Uses Frame Pointers The Perf Trampoline Feature Requires Frame Pointers Distributions Are Waiting for Upstream Mixed Python/C Profiling Requires a Continuous Chain The JIT Compiler Needs Frame Pointers to Be Debuggable The Ecosystem Has Already Adopted Frame Pointers Specification Build System Changes Opt-Out Configure Flag Ecosystem Impact Documentation Updates Platform Scope Rationale Frame Pointers Are a Low-Cost, High-Value Default Detailed Performance Analysis of CPython with Frame Pointers Industry Consensus Has Shifted Decisively Why Not Use CFLAGS_NODIST Instead of BASECFLAGS Alternatives to Frame-Pointer Unwinding Backwards Compatibility Binary Compatibility Performance Extension Build Impact Build Reproducibility Security Implications How to Teach This Reference Implementation Rejected Ideas Change History Footnotes Appendix Copyright Important This PEP is a historical document.

The up-to-date, canonical documentation can now be found at --without-frame-pointers . × See PEP 1 for how to propose changes. Abstract This PEP proposes two things: Build CPython with frame pointers by default on platforms that support them. The default build configuration is changed to compile the interpreter with -fno-omit-frame-pointer and -mno-omit-leaf-frame-pointer . The flags are added to CFLAGS , so they apply to the interpreter itself and propagate to C extension modules built against this Python via sysconfig .

An opt-out configure flag ( --without-frame-pointers ) is provided for deployments that require maximum raw throughput. Strongly recommend that all build systems in the Python ecosystem build with frame pointers by default. This PEP recommends that every compiled component that participates in the Python call stack (C extensions, Rust extensions, embedding applications, and native libraries) should enable frame pointers.

A frame-pointer chain is only as strong as its weakest link: a single library without frame pointers breaks profiling, debugging, and tracing for the entire process. Frame pointers are a CPU register convention that allows profilers, debuggers, and system tracing tools to reconstruct the call stack of a running process quickly and reliably. Omitting them (the compiler’s default at -O1 and above) prevents these tools from producing useful call stacks for Python processes, and undermines the perf trampoline support CPython shipped in 3.12.

The measured overhead is under 2% geometric mean for typical workloads (see Backwards Compatibility for per-platform numbers). Multiple major Linux distributions, language runtimes, and Python ecosystem tools have already adopted this change. No existing PEP covers this topic; CPython issue #96174 has been open since August 2022 without resolution. Motivation Python’s observability story (profiling, debugging, and system-level tracing) is fundamentally limited by the absence of frame pointers.

The core motivation of this PEP is to make Python observable by default, so that profilers are faster and more accurate, debuggers are more reliable, and eBPF-based tools are functional without workarounds. Today, users who want to profile CPython with system tools must rebuild the interpreter with special compiler flags, a step that most users cannot or will not take. The Fedora 38 frame-pointer proposal [2] highlights this as the key problem: without frame pointers in the default build, developers must “recompile their program with sufficient debugging information” and “reproduce the scenario under which the software performed poorly,” which is often impossible for production issues.

Ubuntu 24.04’s analysis [3] makes the same argument: frame pointers “allow bcc-tools, bpftrace, perf and other such tooling to work out of the box.” The goal of this PEP is to make that the default experience for Python. The performance wins that profiling enables far outweigh the modest overhead of frame pointers. As Brendan Gregg notes: “I’ve seen frame pointers help find performance wins ranging from 5% to 500%” [1] .

These wins come from identifying hot paths in production systems; they are not about CPython’s own overhead, but about what profiling enables across the full stack. A 0.5-2% overhead that unlocks such insights is a favourable trade. What Are Frame Pointers? When a program runs, each function call creates a stack frame , a block of memory on the call stack that holds the function’s local variables, its arguments, and the address to return to when the function finishes.

The call stack is the chain of all active stack frames: it records which function called which, all the way from main() to the function currently executing. A frame pointer is a CPU register (for example, %rbp on x86-64, x29 on AArch64) that each function sets to point to the base of its own stack frame. Each frame also stores the previous frame pointer, creating a linked list through the entire call stack: ┌──────────────────┐ │ main() │ ◄─── frame pointer chain │ saved %rbp ─────┼──► (bottom of stack) ├──────────────────┤ │ PyRun_String() │ │ saved %rbp ─────┼──► main's frame ├──────────────────┤ │ _PyEval_Eval…() │ │ saved %rbp ─────┼──► PyRun_String's frame ├──────────────────┤ │ call_function() │ ◄─── current %rbp │ saved %rbp ─────┼──► _PyEval_Eval's frame └──────────────────┘ Stack unwinding is the process of walking this chain to reconstruct the call stack.

Profilers do it to find out where the program is spending time; debuggers do it to show backtraces; crash handlers do it to produce useful error reports. With frame pointers, unwinding is simply following pointers: read %rbp , follow the link, repeat. It requires no external data. At optimisation levels -O1 and above, GCC and Clang omit frame pointers by default [14] . This frees the %rbp register for general use, giving the optimiser one more register to work with.

On x86-64 this is a gain of one register out of 16 (about 7%). The performance benefit is small (typically a few percent) but it was considered worthwhile when the convention was established for 32-bit x86, where the gain was one register out of 6 (~20%). See Detailed Performance Analysis of CPython with Frame Pointers for a full breakdown by platform and workload. Without frame pointers, the linked list does not exist.

Tools that need to walk the call stack must instead parse DWARF debug information (a complex, variable-length encoding of how each function laid out its stack frame) or, on Windows, .pdata / .xdata unwind metadata. This is slower, more fragile, and impossible in some contexts (such as inside the Linux kernel). In the worst case, tools simply produce broken or incomplete results. Here is a concrete example. A perf profile of a Python process without frame pointers typically shows: 100.00 % python libpython3 .14 . so _PyEval_EvalFrameDefault | --- _PyEval_EvalFrameDefault ( truncated , no further frames available ) The same profile with frame pointers shows the full chain: 100

The rest of this page is on the live site.