Python Developer’s Guide
Skip to content
Python Developer's Guide
Getting started
Development workflow
Issues and triaging
Documentation
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
Tutorial
How-to guides
GDB support
Dynamic analysis with Clang
Tools for tracking compiler warnings
Core team
Responsibilities
Accepting pull requests
Experts index
Team log
Motivations and affiliations
How to join the core team
Memorialization
CPython’s internals
Status of Python versions
View this page
Edit this page
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!
Contributing
We encourage everyone to contribute to Python. To help you, 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.
Guide for contributing to Python:
Documentation
Code
Triage
Helping with documentation
Getting started
Style guide
reStructuredText primer
Translating
Helping with the Developer’s Guide
Setup and building
Where to get help
Lifecycle of a pull request
Running and writing tests
Fixing “easy” issues (and beyond)
Following Python’s development
Git bootcamp and cheat sheet
Development cycle
Issue tracker
Triaging an issue
Helping triage issues
Experts index
GitHub labels
GitHub issues for BPO users
Triage Team
We
recommend
that sections of this guide be read as needed. You
can stop where you feel comfortable and begin contributing immediately without
reading and understanding everything. If you do choose to skip
around within the guide, be aware that sections build on each other,
so you may find it necessary to backtrack to fill in
missing concepts and terminology.
A number of individuals from the Python community have contributed to a series
of excellent guides at
Open Source Guides
For example,
How to Contribute to Open Source
Quick reference
Here are the basic steps needed to get set up and open a pull request.
This is meant as a checklist, once you know the basics. For complete
instructions please see the
setup guide
Install and set up
Git
and other dependencies
(see the
Git Setup
page for detailed information).
Fork
the CPython repository
to your GitHub account and
get the source code
using:
git
clone
cd
cpython
Build Python:
Unix
./configure
--with-pydebug
&&
make
-j
$(
nproc
macOS
./configure
--with-pydebug
&&
make
-j8
Windows
PCbuild\build.bat -e -d
See also
more detailed instructions
how to install and build dependencies
and the platform-specific pages for
Unix
macOS
, and
Windows
Run the tests
Unix
./python
-m
test
-j3
macOS
./python.exe
-m
test
-j8
Note
Most
macOS systems use
./python.exe
in order to avoid filename conflicts with
the
Python
directory.
Windows
.\python.bat -m test -j3
Create a new branch where your work for the issue will go, for example:
git
checkout
-b
fix-issue-12345
main
If an issue does not already exist, please
create it
. Trivial issues (for example, typos) do
not require an issue.
Push the branch on your fork on GitHub and
create a pull request
. Include the issue number using
gh-NNNNNN
in the
pull request title. For example:
gh-12345: Fix some bug in spam module
Add a News entry into the
Misc/NEWS.d/
directory as individual file. The
news entry can be created by using
blurb-it
or the
blurb
tool and its
blurb
add
command. Please read more about
blurb
in its
repository
Note
First time contributors will need to sign the Contributor Licensing
Agreement (CLA) as described in the
Licensing
section of
this guide.
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:
Adding to the stdlib
Changing Python
Key resources
Coding style guides
PEP 7
(Style Guide for C Code)
PEP 8
(Style Guide for Python Code)
Issue tracker
Experts index
Buildbot status
Source code
Browse online
Download a snapshot
of the
main
branch
PEPs
(Python Enhancement Proposals)
The Python Discourse
Where to get help
Team log
Git bootcamp and cheat sheet
Additional resources
Anyone can clone the sources for this guide. See
Helping with the Developer’s Guide
Help with …
CPython’s internals
Changing CPython’s grammar
Tool support
GDB support
Dynamic analysis with Clang
Various tools with configuration files as found in the
Misc/
directory
python.org maintenance
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
(for example, Discourse, issue trackers, GitHub, and so on).
In general this means everyone is expected to be open, considerate, and
respectful of others no matter what their position is within the project.
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.
GraalPy
: A Python interpreter which has first-class support for
embedding in Java, built on GraalVM.
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.
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.
Full table of contents
Getting started
Setup and building
Install Git
Get the source code
Compile and build
Install dependencies
Regenerate
configure
Regenerate the ABI dump
Troubleshoot the build
Editors and tools
Directory structure
Using a container
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
Enabling
autocrlf
on Windows
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
Checking out others’ pull requests
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
Introduction
Quick guide
Step-by-step guide
Making good PRs
Updating NEWS and What’s New in Python
Copyrights
Typo fixes
patchcheck
Making good commits
Licensing
Submitting
Converting an existing patch from b.p.o to GitHub
Reviewing
Keeping continuous integration green
Update branch
button
Committing/rejecting
Crediting
Where to get help
Discourse
Ask #python-dev
Core mentorship
File a bug
Generative AI
Acceptable uses
Unacceptable uses
Considerations for success
Development workflow
Following Python’s development
Standards of behaviour in these communication channels
Mailing lists
Discourse (discuss.python.org web forum)
Discord (private chat server)
IRC
Blogs
Setting expectations for open source participation
Additional repositories
Changing Python
Considerations
Suggesting new features and language changes
PEP process
Development cycle
Branches
Stages
Repository administration
Governance
Adding to the stdlib
Adding to a pre-existing module
Adding a new module
Adding a new environment variable
Standard library extension modules
Classifying extension modules
Adding an extension module to CPython
Changing Python’s C API
The internal API
Public C API
Unstable C API
Limited API
Changing CPython’s grammar
Porting to a new platform
Software Bill-of-Materials (SBOM)
Updating a dependency
Adding a new dependency
Removing a dependency
Python Security Response Team (PSRT)
Members
Triaging a vulnerability report
Remediating a vulnerability report
Handling code signing certificate reports
Template responses
Members emeritus
Issues and triaging
Issue tracker
Using the issue tracker
Disagreement with a resolution on the issue tracker
Triaging an issue
Checklist for triaging
Helping triage issues
GitHub labels
Type labels
Component labels
OS labels
Topic labels
Version labels
Other labels
Labels specific to PRs
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
Becoming a member of the Python triage team
Documentation
Getting started
Introduction
Building the documentation
Helping with documentation
Python documentation
Helping with documentation issues
Translating
Proofreading
Style guide
Footnotes
Capitalization
Specific words
Use simple language
Charged terminology to avoid
Diátaxis
Links
Affirmative tone
Author attribution
Pronunciation of dunder names
Economy of expression
Security considerations (and other concerns)
Code examples
Code equivalents
Audience
Function signatures
reStructuredText markup
Quick reference
reStructuredText primer
Typographic conventions
Additional markup constructs
Translations
Translating
Coordinating
Helping with the Developer’s Guide
Developer’s Guide workflow
Testing and buildbots
Running and writing tests
Running
Writing
Benchmarks
Silence warnings from the test suite
Increase test coverage
Common gotchas
Measuring coverage
Filing the issue
Measuring coverage of C code with gcov and lcov
Working with buildbots
In case of trouble
Buildbot failures on pull requests
Triggering on pull requests
Checking results of automatic builds
Stability
Flags-dependent failures
Ordering-dependent failures
Transient failures
New buildbot workers
Preparing for buildbot worker setup
Setting up the buildbot worker
Buildbot worker operation
Required ports
Required resources
Security considerations
Development tools
Argument Clinic
Background
Reference
GDB support
Page moved
CPython tips
Dynamic analysis with Clang
What is Clang?
What are sanitizers?
Clang/LLVM setup
Python build setup
Analyzing the output
Tools for tracking compiler warnings
What to do if a warning check fails GitHub CI
Updating the warning ignore file
Core team
Responsibilities
Communication channels and bug notifications
Sign a contributor agreement
Pull request merging
Expectations
Accepting pull requests
Assessing a pull request
Working with Git
Experts index
Stdlib
Tools
Platforms
Miscellaneous
Experts emeritus
Documentation translations
Team log
Procedure for granting or dropping access
Motivations and affiliations
Published entries
Goals of this page
Limitations on scope
How to join the core team
What it takes
Gaining commit privileges
Poll template
Memorialization
Rationale
The process
CPython’s internals
Status of Python versions
Supported versions
Unsupported versions
Full chart
Status key
On this page
Python Developer’s Guide
Contributing
Quick reference
Proposing changes to Python itself
Key resources
Additional resources
Code of conduct
Other interpreter implementations
Full table of contents