PEP 779: Criteria for supported status for free-threaded Python

PEPs
123

Hi Thomas,

The Steering Council (SC) approves PEP 779, with the effect of removing the “experimental” tag from the free-threaded build of Python 3.14.

Along with this, the SC considers the following requirements must be addressed during Phase II. Meeting these ensures that free-threading support can mature into a safe and scalable default in future versions of Python. This is not an exhaustive list, and any other previous requirements should still be met.

  1. C API/ABI compatibility and Stable ABI for free-threading
    Any proposed changes that break existing API or ABI guarantees must be agreed to in advance with the C API Working Group. Limited C APIs for free-threading must provide a reliable foundation so that third-party library maintainers, particularly those who rely on the C API, can plan their support with confidence. The Steering Council also expects that Stable ABI for free-threading should be prepared and defined for Python 3.15.

  2. Requirements for new experimental projects within CPython
    New experimental projects within CPython must be compatible with, and should be based on the free-threading build. The SC encourages this direction to reduce engineering complexity caused by supporting both GIL and free-threaded builds.

  3. Performance and memory guard rails
    While the official target is to stay within 10% performance degradation, any changes expected to cause a slowdown of up to 15% should be discussed with the SC in advance. We expect a review of the specific changes contributing to such degradation to understand and evaluate their impact. Memory usage increases must stay below 15% compared to the GIL build. Similarly, any changes expected to increase memory above 15% (with a hard limit of 20%) should be discussed with the SC in advance.

  4. Documentation expectations
    Documentation must be clearly written and maintained.

    • For Python users: What guarantees exist, and how are they affected by the free-threaded build on all APIs in all modules of the standard library.
    • For both Python and C API developers: Documentation on signal-safety, thread-safety, and other concurrency-related guarantees in all APIs that are publicly exposed without exceptions.
    • For CPython developers: Documentation on the impact of free-threading and how it should be taken into consideration while working on the language implementation.
    • We recommend a central “free threading landing page”, location to be decided, which provides a guide to all the disparate documentation, PEPs, timelines, other decisions, and information regarding the free threading feature in Python. If https://py-free-threading.github.io/ is that site, we recommend making it an official page and improving its discoverability and visibility (e.g. possibly moving to the python.org domain).

  5. Preparation for high-level concurrency primitives
    The Python core team should begin considering and proposing higher-level concurrency primitives that users can use safely and effectively, without requiring a deep understanding of the underlying threading mechanism. And the SC wishes that this task should be prioritized once the above tasks are stable. We recommend using the concurrent package in the stdlib for this, where appropriate.

  6. Benchmark requirements
    All claims regarding performance, memory usage, and correctness must be supported by comprehensive and repeatable tests. These evaluations should be conducted using the existing benchmark infrastructure based on pyperformance. The SC encourages the community to contribute additional benchmarks, particularly those that are affected by or relevant to free-threading and which better represent real-world workloads, to ensure broad and realistic coverage.

We are confident that the project is on the right path, and we appreciate the continued dedication from everyone working to make free-threading ready for broader adoption across the Python community.

With these recommendations and the acceptance of this PEP, we as the Python developer community should broadly advertise that free-threading is a supported Python build option now and into the future, and that it will not be removed without following a proper deprecation schedule. As approved by the 3.14 Release Manager Hugo van Kemenade, we recommend officially removing the “experimental” tag from the CPython free-threading build with the 3.14 beta 3 release.

Keep in mind that any decision to transition to Phase III, with free-threading as the default or sole build of Python is still undecided, and dependent on many factors both within CPython itself and the community. We leave that decision for the future.

Donghee, on behalf of the Steering Council

Note: This announcement has been updated to clarify terminology. For details, see the updated post.

50 Likes