Python Developer’s Guide#
This guide is a comprehensive resource for contributing to Python – for both new and experienced contributors. It is maintained by the same community that maintains Python. We welcome your contributions to Python!
Here are the basic steps needed to get set up and contribute a patch. This is meant as a checklist, once you know the basics. For complete instructions please see the setup guide.
git clone https://github.com/<your_username>/cpython cd cpython
./configure --with-pydebug && make -j
./configure --with-pydebug && make -j
PCbuild\build.bat -e -d
./python -m test -j3
./python.exe -m test -j3
Note: Most macOS systems use
./python.exein order to avoid filename conflicts with the
.\python.bat -m test -j3
Create a new branch where your work for the issue will go, e.g.:
git checkout -b fix-issue-12345 main
If an issue does not already exist, please create it. Trivial issues (e.g. typo fixes) do not require any issue to be created.
Once you fixed the issue, run the tests, and the patchcheck:
If everything is ok, commit.
Push the branch on your fork on GitHub and create a pull request. Include the issue number using
gh-NNNNin the pull request description. For example:
gh-12345: Fix some bug in spam module
Add a News entry into the
Misc/NEWS.ddirectory as individual file. The news entry can be created by using blurb-it, or the blurb tool and its
blurb addcommand. Please read more about
blurbin its repository.
First time contributors will need to sign the Contributor Licensing Agreement (CLA) as described in the Licensing section of this guide.
We encourage everyone to contribute to Python and that’s why we have put up this developer’s guide. If you still have questions after reviewing the material in this guide, then the Core Python Mentorship group is available to help guide new contributors through the process.
A number of individuals from the Python community have contributed to a series of excellent guides at Open Source Guides.
Core developers and contributors alike will find the following guides useful:
Guide for contributing to Python:
We recommend that the documents in this guide be read as needed. You can stop where you feel comfortable and begin contributing immediately without reading and understanding these documents all at once. If you do choose to skip around within the documentation, be aware that it is written assuming preceding documentation has been read so you may find it necessary to backtrack to fill in missing concepts and terminology.
Proposing changes to Python itself#
Improving Python’s code, documentation and tests are ongoing tasks that are never going to be “finished”, as Python operates as part of an ever-evolving system of technology. An even more challenging ongoing task than these necessary maintenance activities is finding ways to make Python, in the form of the standard library and the language definition, an even better tool in a developer’s toolkit.
While these kinds of change are much rarer than those described above, they do happen and that process is also described as part of this guide:
Other interpreter implementations#
This guide is specifically for contributing to the Python reference interpreter, also known as CPython (while most of the standard library is written in Python, the interpreter core is written in C and integrates most easily with the C and C++ ecosystems).
There are other Python implementations, each with a different focus. Like CPython, they always have more things they would like to do than they have developers to work on them. Some major examples that may be of interest are:
PyPy: A Python interpreter focused on high speed (JIT-compiled) operation on major platforms
Jython: A Python interpreter focused on good integration with the Java Virtual Machine (JVM) environment
IronPython: A Python interpreter focused on good integration with the Common Language Runtime (CLR) provided by .NET and Mono
Stackless: A Python interpreter focused on providing lightweight microthreads while remaining largely compatible with CPython specific extension modules
MicroPython: A tiny Python interpreter with small subset of the Python standard library that is optimised to run on microcontrollers and in constrained environments.
CircuitPython: A fork of MicroPython designed to simplify experimenting and learning to code on low-cost microcontroller boards.
Anyone can clone the sources for this guide. See Helping with the Developer’s Guide.
Help with …
Code of conduct#
Please note that all interactions on Python Software Foundation-supported infrastructure is covered by the PSF Code of Conduct, which includes all infrastructure used in the development of Python itself (e.g. mailing lists, issue trackers, GitHub, etc.). In general this means everyone is expected to be open, considerate, and respectful of others no matter what their position is within the project.
Status of Python branches#
Moved to Status of Python versions
Full table of contents#
- Getting started
- Setup and building
- Fixing “easy” issues (and beyond)
- Git bootcamp and cheat sheet
- Forking CPython GitHub repository
- Cloning a forked CPython repository
- Configure the remotes
- Listing the remote repositories
- Setting up your name and email address
- Creating and switching branches
- Deleting branches
- Renaming branch
- Staging and committing files
- Reverting changes
- Stashing changes
- Comparing changes
- Pushing changes
- Creating a pull request
- Linking to issues and pull requests
- Updating your CPython fork
- Applying a patch to Git
- Downloading other’s patches
- Accepting and merging a pull request
- Cancelling an automatic merge
- Backporting merged changes
- Editing a pull request prior to merging
- GitHub CLI
- Git worktree
- Lifecycle of a pull request
- Where to get help
- Development workflow
- Following Python’s development
- Development cycle
- Adding to the stdlib
- Standard library extension modules
- Changing Python’s C API
- Changing the Python language
- Changing CPython’s grammar
- Porting to a new platform
- Software Bill-of-Materials (SBOM)
- Issues and triaging
- Issue tracker
- Triaging an issue
- GitHub labels
- GitHub issues for BPO users
- How to format my comments nicely?
- How to attach files to an issue?
- How to link to file paths in the repository when writing comments?
- How to do advanced searches?
- Where is the “nosy list”?
- How to add issue dependencies?
- What on earth is a “mannequin”?
- Where did the “resolution” field go?
- Where did the “low”, “high”, and “critical” priorities go?
- How to find a random issue?
- Where are regression labels?
- Triage Team
- Getting started
- Helping with documentation
- Style guide
- reStructuredText markup
- Helping with the Developer’s Guide
- Testing and buildbots
- Running and writing tests
- Silence warnings from the test suite
- Increase test coverage
- Working with buildbots
- New buildbot workers
- Development tools
- Argument Clinic
- GDB support
- Dynamic analysis with Clang
- Coverity Scan
- Core developers
- Accepting pull requests
- Experts index
- Developer log
- Motivations and affiliations
- How to become a core developer
- CPython’s internals
- CPython source code
- Guide to the parser
- Compiler design
- The bytecode interpreter (3.11)
- Garbage collector design
- Status of Python versions