CPython developer proposes one-time stable ABI break

Mark Shannon has proposed a one-time break in CPython’s stable ABI so the core can change the layout of the object header. Under the plan, C extensions would compile for one of two ranges: versions up through 3.15, or 3.12 and later (3.14 and later on 32-bit). A single binary could no longer span both 3.11 and 3.16.

Shannon argues the change would improve maintainability and performance. Homogenizing the header across 64-bit and 32-bit platforms, and between the default and free-threaded builds, would shrink code size, simplify garbage collection and allocator paths, and reduce the diff between the two interpreter modes. He expects a 1-2 percent speedup from simpler checks alone, with larger gains (perhaps 5-10 percent) once allocation, reference counting, and GC can use better structures. Some of that work is possible without a break, he says, but not as cleanly.

The stable ABI has long frozen the header because classic incref and decref macros embedded its layout. Since 3.12 those operations are functions in the stable ABI, so builds limited to 3.12 and newer could tolerate a new layout, though not yet a different header size on 64-bit.

Reaction on discuss.python.org mixed interest with caution. Supporters see room for features such as concurrent garbage collection in free-threading. Critics note that many projects ship abi3 wheels precisely to keep one binary working across Python releases and to ease testing of betas. Emma (emmatyping) called for an explicit list of intended changes and a migration plan before any break. David Hewitt observed that the newer abi3t tag already removes object layout from the stable ABI for free-threaded builds, and that distributors are being steered toward abi3t wheels from 3.15, which could soften the impact for actively maintained projects. Others pointed out that Cython and Nanobind do not yet support abi3t, that older pure-C extensions face heavier C API work, and that packaging tooling plus the length of notice required to break long-standing ABI promises remain open questions.

The proposal is still exploratory; no release target or formal decision has been set.