PEP 831: Frame pointers by pablogsal · Pull Request #4896 · python/peps

pablogsal · 2026-04-09T22:01:21Z

Basic requirements (all PEP Types)

Standards Track requirements

📚 Documentation preview 📚: https://pep-previews--4896.org.readthedocs.build/pep-0831/

peps/pep-0830.rst

savannahostrowski

Given the numbers we've seen, we should update 0.5-2%...if we're rounding up?

peps/pep-0830.rst

JelleZijlstra · 2026-04-10T05:41:24Z

peps/pep-0831.rst

+
+Because the flags are in ``CFLAGS``, they propagate automatically to consumers
+that build against CPython's reported compiler flags, such as C extensions
+built via ``pip``, ``setuptools``, or direct ``sysconfig`` queries.  Those


nit: I don't think pip directly builds any C extension, build backends do that

Suggested change

built via ``pip``, ``setuptools``, or direct ``sysconfig`` queries. Those

built via pip, Setuptools, or direct ``sysconfig`` queries. Those

hugovk

Formatting suggestions.

hugovk · 2026-04-10T09:46:23Z

peps/pep-0831.rst

+
+For all graphs below, the green dots are geometric means of the
+individual benchmark's median, while orange lines are the median of our data points.
+Hollow circles reperesent outliers.


Suggested change

Hollow circles reperesent outliers.

Hollow circles represent outliers.

peps/pep-0831.rst

hugovk · 2026-04-10T09:47:15Z

peps/pep-0831.rst

+   https://github.com/Fidget-Spinner/python-framepointer-bench
+
+.. [#missing_benchmarks] Some benchmarks are missing due to incompatibilities with
+   Python 3.15alpha.


Suggested change

Python 3.15alpha.

Python 3.15 alpha.

hugovk · 2026-04-10T09:55:59Z

peps/pep-0831.rst

+CPython's own documentation already states the recommended fix::
+
+    For best results, Python should be compiled with
+    CFLAGS='-fno-omit-frame-pointer -mno-omit-leaf-frame-pointer'
+    as this allows profilers to unwind using only the frame pointer
+    and not on DWARF debug information.
+
+    -- docs.python.org/3/howto/perf_profiling.html


Fix link, no code formatting for quoting text:

Suggested change

CPython's own documentation already states the recommended fix::

For best results, Python should be compiled with

CFLAGS='-fno-omit-frame-pointer -mno-omit-leaf-frame-pointer'

as this allows profilers to unwind using only the frame pointer

and not on DWARF debug information.

-- docs.python.org/3/howto/perf_profiling.html

:ref:`CPython's own documentation <python:perf_profiling>`__ already states the

recommended fix:

For best results, Python should be compiled with

``CFLAGS="-fno-omit-frame-pointer -mno-omit-leaf-frame-pointer"``

as this allows profilers to unwind using only the frame pointer

and not on DWARF debug information.

hugovk · 2026-04-10T10:23:43Z

peps/pep-0831.rst

+-mno-omit-leaf-frame-pointer``.  However, Ubuntu 24.04 LTS explicitly exempted
+CPython::
+
+    In cases where the impact is high (such as the Python
+    interpreter), we'll continue to omit frame pointers until
+    this is addressed.
+
+    -- ubuntu.com/blog/ubuntu-performance-engineering-with-
+       frame-pointers-by-default


Suggested change

-mno-omit-leaf-frame-pointer``. However, Ubuntu 24.04 LTS explicitly exempted

CPython::

In cases where the impact is high (such as the Python

interpreter), we'll continue to omit frame pointers until

this is addressed.

-- ubuntu.com/blog/ubuntu-performance-engineering-with-

frame-pointers-by-default

-mno-omit-leaf-frame-pointer``. However, Ubuntu 24.04 LTS

`explicitly exempted CPython

<https://ubuntu.com/blog/ubuntu-performance-engineering-with-frame-pointers-by-default>`__:

In cases where the impact is high (such as the Python

interpreter), we'll continue to omit frame pointers until

this is addressed.

hugovk · 2026-04-10T10:25:23Z

peps/pep-0831.rst

+=====================================  =======================
+Apple M2 Mac Mini (arm64)              1.006x slower
+macOS M3 Pro (arm64)                   1.001x slower
+Raspberry Pi (aarch64).                1.002x slower


Suggested change

Raspberry Pi (aarch64). 1.002x slower

Raspberry Pi (aarch64) 1.002x slower

hugovk · 2026-04-10T10:26:28Z

peps/pep-0831.rst

+extension builds. If only the interpreter has frame pointers but extensions do
+not, the chain is still broken at every C extension boundary.  By adding the
+flags to ``CFLAGS`` as reported by ``sysconfig``, extension builds that consume
+CPython's compiler flags (for example via ``pip install``, ``setuptools``, or


Suggested change

CPython's compiler flags (for example via ``pip install``, ``setuptools``, or

CPython's compiler flags (for example via ``pip install``, Setuptools, or

hugovk · 2026-04-10T10:26:39Z

peps/pep-0831.rst

+   the ``python`` binary, ``libpython``, and built-in extension modules under
+   ``Modules/``.
+2. The flags **are** written into the ``sysconfig`` data, so that third-party C
+   extensions built against this Python (via ``pip``, ``setuptools``, or direct


Suggested change

extensions built against this Python (via ``pip``, ``setuptools``, or direct

extensions built against this Python (via pip, Setuptools, or direct

hugovk · 2026-04-10T10:29:34Z

peps/pep-0831.rst

+
+Because the flags are in ``CFLAGS``, they propagate automatically to consumers
+that build against CPython's reported compiler flags, such as C extensions
+built via ``pip``, ``setuptools``, or direct ``sysconfig`` queries.  Those


Suggested change

built via ``pip``, ``setuptools``, or direct ``sysconfig`` queries. Those

built via pip, Setuptools, or direct ``sysconfig`` queries. Those

markshannon

Very compelling.

I'd added a few quick comments on the first part of the PEP.

This is long, and might be a bit much to expect anyone to read through in one go.
Maybe some of the supporting analyses could be moved into appendices and linked to from the body of the PEP?

For example, the detailed, but long, analyses of perf and ebpf tools could be moved to appendices.

markshannon · 2026-04-10T08:12:57Z

peps/pep-0831.rst

+   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 complete as its weakest


Suggested change

frame pointers. A frame-pointer chain is only as complete as its weakest

frame pointers. A frame-pointer chain is only as strong as its weakest

markshannon · 2026-04-10T08:17:37Z

peps/pep-0831.rst

+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.


For what platform, build configuration, etc, etc?
Can you link to the data, otherwise the readers (at least this reader's) first thought is "where's the evidence?"

markshannon · 2026-04-10T08:39:34Z

peps/pep-0831.rst

+==========
+
+Python's observability story (profiling, debugging, and system-level tracing)
+is fundamentally limited by the absence of frame pointers. The core motivation


This isn't quite true. It isn't impossible without frame pointers, just much, much harder.

markshannon · 2026-04-10T08:40:27Z

peps/pep-0831.rst

+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%" [#gregg2024]_.  A 0.5-2% overhead that
+unlocks the ability to find 5-500% improvements is a favourable trade.


Make it clear, that large speedups are not going to happen for CPython, but it might happen for larger systems using Python as a glue language.

markshannon · 2026-04-10T08:43:31Z

peps/pep-0831.rst

+frame also stores the *previous* frame pointer, creating a linked list through
+the entire call stack::
+
+    ┌──────────────────┐


Have the arrows actually point to the previous frame. I think it is OK to use an image,instead of ASCII art.

markshannon · 2026-04-10T08:49:37Z

peps/pep-0831.rst

+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 a simple pointer chase: read


Suggested change

error reports. With frame pointers, unwinding is a simple pointer chase: read

error reports. With frame pointers, unwinding is a simply following pointers: read

I don't know if you can expect the readership to known the term "pointer chasing"

markshannon · 2026-04-10T08:50:35Z

peps/pep-0831.rst

+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 a simple pointer chase: read
+``%rbp``, follow the link, repeat. It takes microseconds and requires no


Suggested change

``%rbp``, follow the link, repeat. It takes microseconds and requires no

``%rbp``, follow the link, repeat. It is very fast and requires no

How long it actually takes depends on many factors.

markshannon · 2026-04-10T08:52:48Z

peps/pep-0831.rst

+default [#gcc_fomit]_.  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 0.5-2%) but it was considered worthwhile when the convention was


Again, you need to be more nuanced about how much things slow down, and for which platforms.

I'd use terms like "a few" rather than 0.5-2 and add a link to a section with a more detailed breakdown

markshannon · 2026-04-10T08:53:47Z

peps/pep-0831.rst

+established for 32-bit x86, where the gain was one register out of 6 (~20%).
+
+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,


Don't forget Windows. It would make your case more compelling, as tools would need to parse DWARF and understand what Windows does.

markshannon · 2026-04-10T08:55:11Z

peps/pep-0831.rst

+follows the chain, and reconstructs the full call stack in microseconds.  This
+is fast enough to sample at 10,000 Hz in production with negligible overhead.
+
+Without frame pointers, the profiler must fall back to DWARF unwinding, a


Didn't you just say this a few paragraphs earlier?
https://github.com/python/peps/pull/4896/changes#diff-cce3082fa07cd352af453f46a4e6f23b15645c79d58cb902da789f5c463cc92aR115

pablogsal requested review from a team and brettcannon as code owners April 9, 2026 22:01

pablogsal and others added 13 commits April 9, 2026 23:03

Frame pointers frame pointers frame pointers

23ea4a5

First pass at edits

984672f

Add ref back

42c762a

Fix flame graph

2025921

Fixed whitespace

3408a2b

Update preamble

4569c5c

Add RPi and M3 results

6c3bde4

Clean up table

87a3af7

Add my benchmarks

2f241a5

Add perf figures, tighten JIT claims

941880e

remove Diego (for now)

009204a

fix typo

bd948d0

Show outliers

02c94e6

pablogsal force-pushed the frame-pointers branch from fd3ea6c to 7c64cc2 Compare April 9, 2026 22:03

pablogsal changed the title ~~Frame pointers~~ PEP 830: Frame pointers Apr 9, 2026

Update pep-0830.rst

1c19495

pablogsal force-pushed the frame-pointers branch from 7c64cc2 to 1c19495 Compare April 9, 2026 22:06

Small fixes

957cecb

brianschubert added the new-pep A new draft PEP submitted for initial review label Apr 9, 2026

brianschubert reviewed Apr 9, 2026

View reviewed changes

peps/pep-0830.rst Outdated Show resolved Hide resolved

savannahostrowski requested changes Apr 9, 2026

View reviewed changes

peps/pep-0830.rst Outdated Show resolved Hide resolved

peps/pep-0830.rst Outdated Show resolved Hide resolved

peps/pep-0830.rst Outdated Show resolved Hide resolved

peps/pep-0830.rst Outdated Show resolved Hide resolved

peps/pep-0830.rst Outdated Show resolved Hide resolved

Address PR feedback

e7faa8c

pablogsal changed the title ~~PEP 830: Frame pointers~~ PEP 831: Frame pointers Apr 9, 2026

JelleZijlstra reviewed Apr 10, 2026

View reviewed changes

hugovk reviewed Apr 10, 2026

View reviewed changes

markshannon reviewed Apr 10, 2026

View reviewed changes

Fidget-Spinner added 2 commits April 11, 2026 00:39

Update new results, add alt text

b231f21

exclude svg from pre-commit

9360134

Fidget-Spinner and others added 2 commits April 11, 2026 00:44

Update .pre-commit-config.yaml

c7269af

Merge pull request #9 from Fidget-Spinner/fp-kj-3

42dcac9

pablogsal requested a review from CAM-Gerlach as a code owner April 10, 2026 18:53

	built via ``pip``, ``setuptools``, or direct ``sysconfig`` queries. Those
	built via pip, Setuptools, or direct ``sysconfig`` queries. Those

	Hollow circles reperesent outliers.
	Hollow circles represent outliers.

	Raspberry Pi (aarch64). 1.002x slower
	Raspberry Pi (aarch64) 1.002x slower

	CPython's compiler flags (for example via ``pip install``, ``setuptools``, or
	CPython's compiler flags (for example via ``pip install``, Setuptools, or

	extensions built against this Python (via ``pip``, ``setuptools``, or direct
	extensions built against this Python (via pip, Setuptools, or direct

	frame pointers. A frame-pointer chain is only as complete as its weakest
	frame pointers. A frame-pointer chain is only as strong as its weakest

	error reports. With frame pointers, unwinding is a simple pointer chase: read
	error reports. With frame pointers, unwinding is a simply following pointers: read

	``%rbp``, follow the link, repeat. It takes microseconds and requires no
	``%rbp``, follow the link, repeat. It is very fast and requires no

Uh oh!

Conversation

pablogsal commented Apr 9, 2026 • edited by hugovk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Basic requirements (all PEP Types)

Standards Track requirements

Uh oh!

Uh oh!

savannahostrowski left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hugovk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markshannon left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

pablogsal commented Apr 9, 2026 •

edited by hugovk

Loading