Contributing#
We very much welcome ideas, questions and relevant contributions from anyonewith an interest in improving the adoption and usage of free-threaded CPython.
Please readthe Code ofConductand be mindful of the community rules while working on the project.
Contributing to this site#
Contributions can be made through issues on and pull requests to thefree-threaded-compatibilityrepository. Ways to contribute include:
- Improvements to the documentation, from new content to copy-editing for clarity.
- Updates to thestatus tracker.
- Add links to relevant examples, blog posts and other content.
- Create example use cases or benchmarks and add them to thelisting of examples.
Contributing to the adoption of free-threading#
There's a ton of work to do here - and a ton of fun and performance to be had!This is perhaps the single most impactful and exciting change to CPython sincethe Python 2 to Python 3 transition. It's going to take the community multipleyears to complete the transition to free-threaded CPython, and your help willbe valuable. Here are some ways to contribute today:
- Start experimenting! If the packages you rely on for some task or application, try running it with a free-threaded interpreter. And consider whether it can benefit performance or functionality-wise from Python-level threading.
- Implement support for free-threading in packages that are still lacking support. We'll try to provide an outline of how to approach that in an open source package below.
News and getting help#
You can join the Free-threaded Python Community Discord using this invite link:https://discord.gg/rqgHCDqdRr.
You can also ask questions in theThreadingcategory of the Python communityDiscourse forum.
Please read and be mindful of community rules. Both communities enforce thePython Software Foundation Code of Conduct.
Implementing support for free-threading in a package#
A good place to start is to check the current status of the package. Are theredocs on free-threading support? Does the issue tracker for the package have anissue about adding free-threading support? If not, is there a relevant PR?Typically, searching for "free-threading", "free-threaded", "GIL", "3.14t" and"cp314t" will allow you to find the relevant issue or PR if it exists.
Note that python 3.13t exists, but we recommend focusing on python 3.14t+ and onward.
If there is no issue yet and you want to contribute support, opening an issueis usually a good next step (please check the projects contribution guidelinesfor details on how the maintainers want you to suggest a new feature). Hereis example content for such an issue:
Title:*Support for free-threaded CPython*I am interested in adding support for free-threading to PROJECT-NAME. I had alook at what it would take to implement that.<!-- INSERT YOUR THOUGHTS SPECIFIC TO THE PACKAGE HERE:-Are there relevant threading-related issues or docs?-If there are native libraries (C, C++, etc.), are they thread-safe? Does code in the package already drop the GIL?-Is there relevant global state?-Are there particular parts of the code base for which dedicated multi-threaded tests should be written?-->The standard TODOs for adding free-threading support are:- [ ] Audit Python bindings and declare them free-threading compatible (xref https://py-free-threading.github.io/porting/#updating-extension-modules).- [ ] Run the test suite with`pytest-run-parallel` to find potential issues, and fix them.- [ ] Run the test suite under [Thread Sanitizer](thread_sanitizer.md)._If possible, depends on how many dependencies there are and if they run under TSan._- [ ] Add`cp314t-*` (and`cp313t-*`) to CI to build free-threading wheels.For more details, please see the[suggested plan of attack in the py-free-threading guide](https://py-free-threading.github.io/porting/#suggested-plan-of-attack).Note that this is the first time I've looked at this repo, so I might bemissing known issues or code that needs closer inspection. Any suggestions herewill be very useful.I will be happy to help and work on this. Please do let me know if you'd preferme to hold off for any reason.