The
is hosted on GitHub, alongside the codebase and pull requests.
Note
Prior to moving the issue tracker to GitHub, Python used to use a dedicated
instance as its issue tracker. That
was hosted under the domain bugs.python.org (sometimes called bpo or BPO for short). A read-only version is available on that domain for historical purposes. All bpo data has been migrated to the current issue tracker on GitHub. Old issues are still referenced in the bpo-NNN format, where bpo-12345 refers to https://bugs.python.org/issue12345.
Reporting an issue
If you think you have found a bug in Python, you can report it to the
. Documentation bugs can also be reported there.
If you would like to file an issue about this devguide, please do so in the
instead.
Checking if a bug already exists
The first step before filing an issue report is to see whether the problem has already been reported. Checking if the problem is an existing issue will:
help you see if the problem has already been resolved or has been fixed for the next release
save time for you and the developers
help you learn what needs to be done to fix it
determine if additional information, such as how to replicate the issue, is needed
To see if an issue already exists, search the bug database using the search box above the list of bugs on the issues page. See
for more information.
Creating a new issue
If the problem you’re reporting is not already in the
, you can report it using the green New issue button on the right of the search box above the list of bugs. If you’re not already signed in to GitHub, it will ask you to do so now.
First you need to select what kind of problem you want to report. The available choices include, for example:
Bug report: an existing feature isn’t working as expected.
Documentation: there is missing, invalid, or misleading documentation.
Feature or enhancement: suggest a new feature for Python.
Report a security vulnerability: privately report a security vulnerability.
Depending on your choice, a dedicated form template will appear. In particular, you’ll notice that one of the buttons actually takes you to the
(discuss.python.org), where many Python-related discussions take place.
The submission form has only two fields that you need to fill:
in the Title field, enter a very short description of the problem; less than ten words is good; don’t include “labels” like [feature] as we use GitHub labels;
in the Write field, describe the problem in detail using hints from the template that was put in that field for you. Be sure to include what you expected to happen, what did happen, and how to replicate the problem. Be sure to include whether any extension modules were involved, and what hardware and software platform you were using (including version information as appropriate). In particular, what version of Python you were using.
You can tag someone, with @username in a comment, if you think the issue should be brought to their attention. Use the
to know who wants to be tagged or assigned for specific areas.
There are a number of additional fields like Assignees, Labels, and Projects. Those are filled by triagers and core team members and are covered in the
page. You don’t need to worry about those when reporting issues as a Python user.
Working with issues
This section covers common tasks on the issue tracker, such as searching, commenting on, and following issues.
Searching issues
Use the
or the interactive
form that generates search queries for you.
You can also narrow down the results by filtering by label, either with the Labels dropdown above the list of issues or with the label:name search qualifier. See
for an overview of the labels used in the CPython repository.
Formatting issues and comments
There is a wonderful
beginner guide to writing and formatting on GitHub
. Highly recommended.
One pro-tip we can sell you right here is that if you want to paste some longer log as a comment,
. If you still insist on pasting it in your comment, wrap it with a
using <details></details> for better readability:
<details> <summary>This is the summary text, click me to expand</summary> Here goes the long, long text. It will be collapsed by default! </details> Attaching files
Drag them into the comment field, wait until the file uploads, and GitHub will automatically put a link to your file in your comment text.
Adding links
The following abbreviations can be used in a comment to generate a link:
GH-NNN: to link to another issue or PR;
PEP-NNN: to link to a specific PEP;
BPO-NNN: to link to a bugs.python.org issue;
See also the
list of autolinks supported by GitHub
.
To link to a file in the repository, you can get a permanent link to a given revision of the file by
.
Following issues
If you want to subscribe yourself to an issue, click the 🔔 Subscribe button in the sidebar. Subscribe another person to the issue by tagging them in a comment with @username. If you were tagged by somebody else but decided this issue is not for you, click the 🔕 Unsubscribe button in the sidebar. Note that you are automatically subscribed to issues you create or comment on.
Tracking dependencies and duplicates
It is possible to
create relationships between issues
to track dependencies and in case of meta-issues, to
to link to the other related issues.
By writing Duplicateof#NNN in a comment, you can
mark issues and PRs as duplicates
.
Mannequin accounts
For old issues migrated to GitHub from bugs.python.org (BPO) where the authors or commenters were not core team members, we opted not to link to their GitHub accounts directly. Users not in the
might not like comments to appear under their name from an automated import. Others never linked GitHub on BPO in the first place so linking their account, if any, would be impossible.
In those cases a “mannequin” account is present to help follow the conversation that happened in the issue. In case the user did share their GitHub account name in their BPO profile, we use that. Otherwise, their classic BPO username is used instead.
Disagreement with a resolution
As humans, we will have differences of opinions from time to time. First and foremost, please be respectful that care, thought, and volunteer time went into the resolution. Keep in mind that contributors come from many different cultural and linguistic backgrounds; see
Communicating across cultures and languages
.
With this in mind, take some time to consider any comments made in association with the resolution of the issue. On reflection, the resolution steps may seem more reasonable than you initially thought.
If you still feel the resolution is incorrect, then raise a thoughtful question on the
Core Development Discourse category
. Further argument and disrespectful responses after a consensus has been reached amongst the core developers is unlikely to win any converts.
As a reminder, issues closed by a core developer have already been carefully considered. Please do not reopen a closed issue. An issue can be closed with reason either as complete or notplanned.