This section of the documentation is currently being written. pip developers welcome your help to complete this documentation. If you’re interested in helping out, please let us know in the tracking issue, or just submit a pull request and mention it in that tracking issue.
This serves as an introduction to issue tracking in pip as well as how to help triage reported issues.
The pip issue tracker is hosted on GitHub alongside the project.
Currently, the issue tracker is used for bugs, feature requests, and general user support.
In the pip issue tracker, we make use of labels and milestones to organize and track work.
Issue labels are used to:
Provide status information for contributors and reporters
Help contributors find tasks to work on
The current set of labels are divided into several categories identified by prefix:
- C - Category
which area of
pipfunctionality a feature request or issue is related to
K - Kind
- O - Operating System
for issues that are OS-specific
- P - Project/Platform
related to something external to
- R - Resolution
no more discussion is really needed, an action has been identified and the issue is waiting or closed
- S - State
for some automatic labels and other indicators that work is needed
the role or flavor of an issue
The specific labels falling into each category have a description that can be seen on the Labels page.
In addition, there are several standalone labels:
- good first issue
this label marks an issue as beginner-friendly and shows up in banners that GitHub displays for first-time visitors to the repository
default label given to issues when they are created
special label for pull requests that removes the news file requirement
- needs rebase or merge
this is a special label used by BrownTruck to mark PRs that have merge conflicts
There are several helpers to manage issues and pull requests.
Issues created on the issue tracker are automatically given the
triage label by the
bot. The label is automatically removed when another label is added.
When an issue needs feedback from the author we can label it with
S: awaiting response. When the author responds, the
no-response bot removes the label.
After an issue has been closed for 30 days, the
lock bot locks the issue and adds the
S: auto-locked label. This allows us to avoid monitoring existing closed
issues, but unfortunately prevents and references to issues from showing up as
links on the closed issue.
Users can make issues for a number of reasons:
Suggestions about pip features that could be added or improved
Problems using pip
Concerns about pip usability
General packaging problems to be solved with pip
Problems installing or using Python packages
Problems managing virtual environments
Problems managing Python installations
To triage issues means to identify what kind of issue is happening and
discuss and design around the uses of the tool
Specifically, to address an issue:
Read issue title
Scan issue description
If time is available, try to reproduce
Search for or remember related issues and link to them
Identify an appropriate area of concern (if applicable)
Keep in mind that all communication is happening with other people and should be done with respect per the Code of Conduct.
The lifecycle of an issue (bug or support) generally looks like:
waiting for triage (marked with label
confirming issue - some discussion with the user, gathering details, trying to reproduce the issue (may be marked with a specific category,
S: discussion-needed, or
confirmed - the issue is pretty consistently reproducible in a straightforward way, or a mechanism that could be causing the issue has been identified
awaiting fix - the fix is identified and no real discussion on the issue is needed, should be marked
R: awaiting PR
closed - can be for several reasons
could not be reproduced, no more details could be obtained, and no progress can be made
actual issue was with another project or related to system configuration and pip cannot (or will not) be adapted for it
Requesting more information to better understand the context and environment that led to the issue. Examples of specific information that may be useful depending on the situation:
python -c 'import sys; print(sys.executable)'
which python; Windows:
Python as resolved by the shell:
Origin of pip (get-pip.py, OS-level package manager, ensurepip, manual installation)
Using a virtual environment (with
Using a conda environment
Network situation (e.g. airgapped environment, firewalls)
--verboseoutput of a failing command
straceoutput from a failing command (be careful not to output into the same directory as a package that’s being installed, otherwise pip will loop forever copying the log file…)
Listing of files relevant to the issue (e.g.
ls -l venv/lib/pythonX.Y/problem-package.dist-info/)
whether the unexpected behavior ever worked as expected - if so then what were the details of the setup (same information as above)
Generally, information is good to request if it can help confirm or rule out possible sources of error. We shouldn’t request information that does not improve our understanding of the situation.
Whenever an issue happens and the cause isn’t obvious, it is important that we be able to reproduce it independently. This serves several purposes:
If it is a pip bug, then any fix will need tests - a good reproducer is most of the way towards that.
If it is not reproducible using the provided instructions, that helps rule out a lot of possible causes.
A clear set of instructions is an easy way to get on the same page as someone reporting an issue.
The best way to reproduce an issue is with a script.
A script can be copied into a file and executed, whereas shell output has to be manually copied a line at a time.
Scripts to reproduce issues should be:
portable (few/no assumptions about the system, other that it being Unix or Windows as applicable)
require little/no setup on the part of the runner
creating and installing multiple wheels with different versions (link)
using a small web server for authentication errors (link)
using docker to test system or global configuration-related issues (link)
using docker to test special filesystem permission/configurations (link)
using docker for global installation with get-pip (link)
get-pip on system with no
pipfrom current development branch (link)
Some user support questions are more related to system configuration than pip. It’s important to treat these issues with the same care and attention as others, specifically:
Unless the issue is very old and the user doesn’t seem active, wait for confirmation before closing the issue
Direct the user to the most appropriate forum for their questions:
Just because a user support question is best solved using some other forum doesn’t mean that we can’t make things easier. Try to extract and understand from the user query how things could have been made easier for them or you, for example with better warning or error messages. If an issue does not exist covering that case then create one. If an issue does exist then make sure to reference that issue before closing this one.
A user may be having trouble installing a package, where the package
setup.pyor build-backend configuration is non-trivial. In these cases we can help to troubleshoot but the best advice is going to be to direct them to the support channels for the related projects.
Do not be hasty to assume it is one cause or another. What looks like someone else’s problem may still be an issue in pip or at least something that could be improved.
For general discussion on Python packaging:
An issue may be considered resolved and closed when:
for each possible improvement or problem represented in the issue discussion:
Consensus has been reached on a specific action and the actions appear to be external to the project, with no follow up needed in the project afterwards.
PEP updates (with a corresponding issue in python/peps)
already tracked by another issue
A project-specific issue has been identified and the issue no longer occurs as of the latest commit on the main branch.
An enhancement or feature request no longer has a proponent and the maintainers don’t think it’s worth keeping open.
An issue has been identified as a duplicate, and it is clearly a duplicate (i.e. the original report was very good and points directly to the issue)
The issue has been fixed, and can be independently validated as no longer being an issue. If this is with code then the specific change/PR that led to it should be identified and posted for tracking.
network-related issues - any issue involving retries, address lookup, or anything like that are typically network issues.
issues related to having multiple Python versions, or an OS package manager-managed pip/python installation (specifically with Debian/Ubuntu). These typically present themselves as:
Not being able to find installed packages
basic libraries not able to be found, fundamental OS components missing
In these situations you will want to make sure that we know how they got their Python and pip. Knowing the relevant package manager commands can help, e.g.