Text of peps.python.org › pep-0803 as Styx crawled it on Nov 19, 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 803 – “abi3t”: Stable ABI for Free-Threaded Builds | peps.python.org

PEP 803 – “abi3t”: Stable ABI for Free-Threaded Builds PEP 803 – “abi3t”: Stable ABI for Free-Threaded Builds Author : Petr Viktorin <encukou at gmail.com>, Nathan Goldbaum <nathan.goldbaum at gmail.com> Discussions-To : Discourse thread Status : Final Type : Standards Track Requires : 703 , 793 , 697 Created : 19-Aug-2025 Python-Version : 3.15 Post-History : 08-Sep-2025 , 20-Nov-2025 , 16-Feb-2026 Resolution : 30-Mar-2026 Table of Contents Abstract Terminology Motivation Background & Summary Ecosystem maintainers want decreased maintenance burden Cryptography moocore Pydantic SciPy Bindings generators Rationale Separate ABI No backwards compatibility now Source changes are necessary in extensions Tag name Filename tag Knob name Specification Stable ABI for free-threaded builds Choosing the target ABI Opaque PyObject Implications Runtime ABI checks Check for non-free-threaded ABI in free-threading builds The abi3t wheel and filename tags Recommendations for installers Recommendations for build tools New API Backwards and Forwards Compatibility Compatibility Overview Security Implications How to Teach This Reference Implementation Rejected Ideas Single new ABI: make PyObject opaque in Stable ABI 3.15 Shims for compatibility with CPython 3.14 Making abi3t compatible with abi3 Naming this abi4 abi3+abi3t filename tag No filename tag (bare .so ) Reusing Py_GIL_DISABLED to enable the new ABI Fully separate ABIs, keeping source compatibility Copyright Important This PEP is a historical document.

The up-to-date, canonical documentation can now be found at Stable Application Binary Interfaces and Migrating to Stable ABI for free threading (abi3t) . × See PEP 1 for how to propose changes. Abstract Add a new variant of the Stable ABI, called “Stable ABI for Free-Threaded Python” (or abi3t for short). abi3t will be based on the existing Stable ABI ( abi3 ), but make the PyObject structure opaque. This will require users to migrate to new API for common tasks like defining modules and most classes.

In practice, abi3t 3.15 will be compatible with abi3 3.15. Extension authors are encouraged to explicitly compile for both ABIs at once, and signal compatibility using the wheel tag abi3.abi3t . Terminology This PEP uses “GIL-enabled build” as an antonym to “free-threaded build”, that is, an interpreter or extension built without Py_GIL_DISABLED . Motivation The Stable ABI is currently not available for free-threaded builds.

Extensions will fail to build for the Stable ABI on free-threaded Python (that is, when both Py_LIMITED_API and Py_GIL_DISABLED preprocessor macros are defined). Extensions built for GIL-enabled builds of CPython will fail to load (or crash) on free-threaded builds. In its acceptance post for PEP 779 , the Steering Council stated that it “expects that Stable ABI for free-threading should be prepared and defined for Python 3.15”.

This PEP proposes the Stable ABI for free-threading. Background & Summary Python’s Stable ABI ( abi3 for short), as defined in PEP 384 and PEP 652 , provides a way to compile extension modules that can be loaded on multiple minor versions of the CPython interpreter. Several projects use this to limit the number of wheels (binary artefacts) that need to be built and distributed for each release, and/or to make it easier to test with pre-release versions of Python.

With free-threading builds ( PEP 703 ) being on track to eventually become the default ( PEP 779 ), we need a way to make a Stable ABI available to those builds. The current Stable ABI is versioned, and an extension built for Stable ABI 3.X is ABI-compatible with CPython 3.X and any later version (though bugs in CPython sometimes cause incompatibilities in practice). However, this forward compatibility is only guaranteed for a subset of the API that CPython exposes (functions, structures, etc.).

Extensions that target the Stable ABI must limit themselves to this subset, called the Limited API . When the “opt-in” preprocessor macro Py_LIMITED_API is defined, CPython headers will expose the Limited API only This PEP proposes a stable ABI for free-threading builds ( abi3t for short), which includes additional API limitations needed to compile extensions compatible with both GIL-enabled and free-threaded builds of CPython 3.15+, a corresponding macro to opt in to these limitations, and naming/tagging schemes that extensions should use to signal such compatibility.

Ecosystem maintainers want decreased maintenance burden A major advantage of the limited API and stable ABI wheels is that new Python versions are supported on the day of release. Without stable ABI wheels, maintainers are left with a choice between closely following CPython releases and producing wheels during CPython beta periods or dealing with inevitable user requests for support for new CPython versions. Cryptography The cryptography project shipped 48 wheel files with their most recent release .

Cryptography is somewhat unusual in that they ship 14 wheels each for both the cp38 and cp311 stable ABIs to enable optimizations available in newer limited API versions. They also ship 14 additional cp314t wheels and 6 wheels for PyPy. If there is no free-threaded stable ABI, then with Python 3.15, cryptography will be using roughly the same amount of space on PyPI to support two versions of the free-threaded build as all non-EOL versions of the GIL-enabled build.

Cryptography maintainer Alex Gaynor expressed a desire on Discourse for a free-threaded stable ABI: Just to state this explicitly from the PyCA maintainers perspective, as long as we have O(1) builds, that’s ok. What we can’t/won’t do is O(n) where we need new builds for every Python release. When one of the PEP authors asked Alex in the #pyca Libera IRC channel for his current opinion, he said: One other thing I’ll note that’s really valuable about abi3 is that it means our old wheels keep working for new Python versions.

If we have per-Python release wheels, we have to do a bunch of work at various points in the python release cycle (including potentially backport releases to add new wheels, if we’re not otherwise planning a release at that time). As maintainers, we really like to structure our work to avoid being “on the clock” like that. moocore The moocore project ships seven abi3 wheels. When the topic of adding support for the free-threaded build came up on the moocore issue tracker , maintainer Manuel López-Ibáñez let the person reporting the issue know that: I don’t want to build for 3.14 free-threading unless you really need it.

Later, after discovering the tracking issue for supporting the limited API on the free-threaded build, he commented: By the way, python/cpython#111506 is about extending the stable ABI to support free-threaded Python. If they do that, then the builds of moocore will work in both classical and free-threaded Python versions, without needing to build new wheels for each Python version. […] I will revisit this again once Python 3.15 is released.

Hopefully the ABI will be stable (or even better, free-threading will be the default). Pydantic Pydantic maintainer David Hewitt observed : Pydantic distributes wheels for a native core built using Rust & PyO3. The latest release of pydantic-core distributed 112 wheels and this number is set to grow as more environments are to be added (e.g. Android, iOS, wasm). Pydantic has historically not distributed using the stable ABI because the feature set was too immature.

Much Pydantic functionality interacts with Python objects via the C API in hot loops so performance is key concern. As the stable ABI matures it will be ideal for Pydantic to switch tier 2 platforms to the stable ABI (and perhaps eventually tier 1 platforms too), which will significantly reduce the number of wheels to build, test, and distribute. I would like to highlight that if free-threading does not adopt a stable ABI, all the benefits above will be lost

The rest of this page is on the live site.