gh-146636: Add Free-threaded Stable ABI migration guide by encukou · Pull Request #150580 · python/cpython

encukou · 2026-05-29T16:26:41Z

Issue: Implement PEP 803 -- abi3t #146636

This document provides detailed instructions on how to use the Free Threading Stable ABI in CPython, including guidelines for module initialization, API usage, and thread safety considerations.

Clarified access restrictions on PyObject members and recommended functions for type and reference count manipulation.

Clarified that direct access to PyObject members is prohibited.

Co-authored-by: da-woods <dw-git@d-woods.co.uk>

Updated documentation to clarify the identification of free-threaded limited API builds in C, including changes to macros and initialization methods.

Updated the documentation to clarify the use of the stable ABI and GIL management in Python extensions, including changes to member access and initialization methods.

Removed sections on API guidelines, critical sections, and thread safety from the documentation.

read-the-docs-community · 2026-05-29T16:30:54Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #32935333 | 📁 Comparing d89c007 against main (26696a6)

🔍 Preview build

28 files changed · + 1 added · ± 27 modified

+ Added

howto/abi3t-migration.html

± Modified

ngoldbaum · 2026-05-29T16:57:05Z

Thanks, this looks great! I'll probably use the tables in my EuroPython talk.

I'm hopeful that we'll be able to ship abi3t support in the next releases of PyO3 and Maturin (see PyO3/pyo3#5807 and PyO3/maturin#3113).

I am also planning to add a section to the free-threaded guide about building abi3t extensions, including practicalities like dealing with bindings generators and the NumPy C API. When that is ready, maybe we can just link there for all the ecosystem-wide details that don't belong in the CPython docs?

StanFromIreland · 2026-05-29T17:50:05Z

+-----------------+-------------------+------------------+
+| 3.16            | ``cpython-316``   | ``cpython-316t`` |
+-----------------+-------------------+------------------+
+| Future versions | (etc.)            | (etc.)           |


StanFromIreland · 2026-05-29T17:50:31Z

+-----------------+                   +------------------+
+| 3.16            |                   | ``cpython-316t`` |
+-----------------+                   +------------------+
+| Future versions |                   | (etc.)           |


StanFromIreland · 2026-05-29T18:06:28Z

+changes extensions may need.
+
+If you find a problem that other extension authors might run into,
+consider submitting an issue (or pull request) for this guide.


Maybe add a link to https://docs.python.org/3/bugs.html?

Co-authored-by: da-woods <dw-git@d-woods.co.uk> Co-authored-by: Stan Ulbrych <stan@python.org>

encukou · 2026-06-01T12:56:07Z

Thanks for the reviews and suggestions!

I am also planning to add a section to the free-threaded guide about building abi3t extensions, including practicalities like dealing with bindings generators and the NumPy C API. When that is ready, maybe we can just link there for all the ecosystem-wide details that don't belong in the CPython docs?

That sounds great!

hugovk · 2026-06-01T14:44:36Z

+******************************************************
+Migrating to Stable ABI for Free Threading (``abi3t``)
+******************************************************


Use sentence case for headers:

https://devguide.python.org/documentation/style-guide/#capitalization

Suggested change

******************************************************

Migrating to Stable ABI for Free Threading (``abi3t``)

******************************************************

******************************************************

Migrating to Stable ABI for free threading (``abi3t``)

******************************************************

hugovk · 2026-06-01T14:49:32Z

+-----------------+-----------------------+------------------------+
+| 3.16            | ``cpython-316``       | ``cpython-316t``       |
+-----------------+-----------------------+------------------------+
+| Later versions  | :samp:`cpython-3{YY}` | :samp:`cpython-3{YY}t` |


I suggest XX as the first unknown, to avoid any confusion with YY for the year in CalVer, and the similar "3.x" is more common than "3.y".

Suggested change

| Later versions | :samp:`cpython-3{YY}` | :samp:`cpython-3{YY}t` |

| Later versions | :samp:`cpython-3{XX}` | :samp:`cpython-3{XX}t` |

hugovk · 2026-06-01T14:50:10Z

+-----------------+                   +------------------------+
+| 3.16            |                   | ``cpython-316t``       |
+-----------------+                   +------------------------+
+| Later versions  |                   | :samp:`cpython-3{YY}t` |


Suggested change

| Later versions | | :samp:`cpython-3{YY}t` |

| Later versions | | :samp:`cpython-3{XX}t` |

hugovk · 2026-06-01T14:53:54Z

+Extensions need to be ported to build for Stable ABI, which may be difficult
+or, in rare cases, impossible.
+
+Specifically, ``abi3t`` requires on API added in CPython 3.15.


?

Suggested change

Specifically, ``abi3t`` requires on API added in CPython 3.15.

Specifically, ``abi3t`` requires an API added in CPython 3.15.

hugovk · 2026-06-01T14:56:21Z

+.. seealso::
+
+   `Porting Extension Modules to Support Free-Threading
+   <https://py-free-threading.github.io/porting/>`_:


Prefer anon links:

Suggested change

<https://py-free-threading.github.io/porting/>`_:

<https://py-free-threading.github.io/porting/>`__:

hugovk · 2026-06-01T14:56:47Z

+Isolating Extension Modules
+---------------------------


Suggested change

Isolating Extension Modules

---------------------------

Isolating extension modules

---------------------------

hugovk · 2026-06-01T14:59:06Z

+       return my_slot_array;
+   }
+
+Leave out any fields that were missing (excexpt the new :c:macro:`Py_mod_abi`),


Suggested change

Leave out any fields that were missing (excexpt the new :c:macro:`Py_mod_abi`),

Leave out any fields that were missing (except the new :c:macro:`Py_mod_abi`),

hugovk · 2026-06-01T15:02:50Z

+your classes' data, will need to be rewritten.
+This will probably be the biggest change you need to support ``abi3t``.
+
+For each such type:


The steps following this could be a bullet list.

hugovk · 2026-06-01T15:04:07Z

+
+If you distribute the extension as a *wheel*, use the following tags:
+
+* Python tag: :samp:`cp3{YY}`, where *YY* is the minimum Python version


Suggested change

* Python tag: :samp:`cp3{YY}`, where *YY* is the minimum Python version

* Python tag: :samp:`cp3{XX}`, where *XX* is the minimum Python version

clin1234 and others added 20 commits May 17, 2026 05:33

Add reference to freethreading-stable-abi-howto

8040796

Add documentation for Free Threading Stable ABI usage

7175e14

This document provides detailed instructions on how to use the Free Threading Stable ABI in CPython, including guidelines for module initialization, API usage, and thread safety considerations.

Update documentation on PyObject opaqueness and module init

e0f3bd2

Clarified access restrictions on PyObject members and recommended functions for type and reference count manipulation.

Fix formatting for PyObject opaqueness section

3739aec

Fix formatting of code snippet in documentation

c235a75

Update documentation on PyObject opaqueness

753156b

Clarified that direct access to PyObject members is prohibited.

Py_Type

344105e

Co-authored-by: da-woods <dw-git@d-woods.co.uk>

Clarify free-threaded limited API build documentation

29b932d

Updated documentation to clarify the identification of free-threaded limited API builds in C, including changes to macros and initialization methods.

Revise freethreading-stable-abi.rst for clarity

8545eeb

Updated the documentation to clarify the use of the stable ABI and GIL management in Python extensions, including changes to member access and initialization methods.

Add freethreading-stable-abi.rst to documentation index

2a11368

Simplify threading and API guidelines in documentation

2f2e756

Removed sections on API guidelines, critical sections, and thread safety from the documentation.

Update freethreading-stable-abi.rst

5d23810

Update freethreading-stable-abi.rst

a8294fa

Update freethreading-stable-abi.rst

43538cf

Update module slot definitions to use PySlot from PEP 820

ed0e4fe

Update freethreading-stable-abi.rst

a7fcbcc

Fix typo in freethreading-stable-abi.rst

ccdedb0

Update freethreading-stable-abi.rst

3b401db

Merge in the main branch

a7fdaaf

Rewrite as a guide

cb9545a

encukou requested review from AA-Turner, StanFromIreland and hugovk as code owners May 29, 2026 16:26

bedevere-app Bot mentioned this pull request May 29, 2026

Implement PEP 803 -- abi3t #146636

Open

9 tasks

bedevere-app Bot added the awaiting core review label May 29, 2026

encukou mentioned this pull request May 29, 2026

gh-146636: Add Free-threaded Stable ABI migration guide #148453

Closed

encukou added the skip news label May 29, 2026

encukou added 2 commits May 29, 2026 18:33

Clarification

22a9bfe

No static types

1448abd

da-woods reviewed May 29, 2026

View reviewed changes

Comment thread Doc/howto/abi3t-migration.rst Outdated

StanFromIreland reviewed May 29, 2026

View reviewed changes

encukou mentioned this pull request Jun 1, 2026

Mark various accepted PEPs as Final python/peps#4986

Open

encukou and others added 3 commits June 1, 2026 14:15

Apply suggestions from code review

fcc553a

Co-authored-by: da-woods <dw-git@d-woods.co.uk> Co-authored-by: Stan Ulbrych <stan@python.org>

Address reviews

6d8dc71

Add link to What's New

d89c007

hugovk reviewed Jun 1, 2026

View reviewed changes

	\| Future versions \| (etc.) \| (etc.) \|
	\| Future versions \| ``cpython-X`` \| ``cpython-Xt`` \|

	\| Future versions \| \| (etc.) \|
	\| Future versions \| \| ``cpython-Xt`` \|

	\| Later versions \| :samp:`cpython-3{YY}` \| :samp:`cpython-3{YY}t` \|
	\| Later versions \| :samp:`cpython-3{XX}` \| :samp:`cpython-3{XX}t` \|

	\| Later versions \| \| :samp:`cpython-3{YY}t` \|
	\| Later versions \| \| :samp:`cpython-3{XX}t` \|

	Specifically, ``abi3t`` requires on API added in CPython 3.15.
	Specifically, ``abi3t`` requires an API added in CPython 3.15.

	<https://py-free-threading.github.io/porting/>`_:
	<https://py-free-threading.github.io/porting/>`__:

	Leave out any fields that were missing (excexpt the new :c:macro:`Py_mod_abi`),
	Leave out any fields that were missing (except the new :c:macro:`Py_mod_abi`),


		If you distribute the extension as a wheel, use the following tags:

		* Python tag: :samp:`cp3{YY}`, where YY is the minimum Python version

	* Python tag: :samp:`cp3{YY}`, where YY is the minimum Python version
	* Python tag: :samp:`cp3{XX}`, where XX is the minimum Python version

Uh oh!

Conversation

encukou commented May 29, 2026 • edited by bedevere-app Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Uh oh!

ngoldbaum commented May 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

encukou commented Jun 1, 2026

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!

6 participants

encukou commented May 29, 2026 •

edited by bedevere-app Bot

Loading

read-the-docs-community Bot commented May 29, 2026 •

edited

Loading