<!doctype html>
<html class="no-js" lang="en" data-content_root="../">
<head><meta charset="utf-8"/>
<meta name="viewport" content="width=device-width,initial-scale=1"/>
<meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="search" title="Search" href="../search.html" /><link rel="copyright" title="Copyright" href="../copyright.html" /><link rel="next" title="Architecture of pip’s internals" href="architecture/index.html" /><link rel="prev" title="Continuous Integration" href="ci.html" />
<!-- Generated with Sphinx 8.1.3 and Furo 2024.08.06 -->
<title>Issue Triage - pip documentation v25.1.1</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=a746c00c" />
<link rel="stylesheet" type="text/css" href="../_static/styles/furo.css?v=ad9e2e31" />
<link rel="stylesheet" type="text/css" href="../_static/copybutton.css?v=76b2166b" />
<link rel="stylesheet" type="text/css" href="../_static/tabs.css?v=4c969af8" />
<link rel="stylesheet" type="text/css" href="../_static/styles/furo-extensions.css?v=4aa03575" />
<style>
body {
--color-code-background: #f8f8f8;
--color-code-foreground: black;
}
@media not print {
body[data-theme="dark"] {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
@media (prefers-color-scheme: dark) {
body:not([data-theme="light"]) {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
}
}
</style></head>
<body>
<script>
document.body.dataset.theme = localStorage.getItem("theme") || "auto";
</script>
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
<symbol id="svg-toc" viewBox="0 0 24 24">
<title>Contents</title>
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
<path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
</svg>
</symbol>
<symbol id="svg-menu" viewBox="0 0 24 24">
<title>Menu</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
<line x1="3" y1="12" x2="21" y2="12"></line>
<line x1="3" y1="6" x2="21" y2="6"></line>
<line x1="3" y1="18" x2="21" y2="18"></line>
</svg>
</symbol>
<symbol id="svg-arrow-right" viewBox="0 0 24 24">
<title>Expand</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
<polyline points="9 18 15 12 9 6"></polyline>
</svg>
</symbol>
<symbol id="svg-sun" viewBox="0 0 24 24">
<title>Light mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
<circle cx="12" cy="12" r="5"></circle>
<line x1="12" y1="1" x2="12" y2="3"></line>
<line x1="12" y1="21" x2="12" y2="23"></line>
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
<line x1="1" y1="12" x2="3" y2="12"></line>
<line x1="21" y1="12" x2="23" y2="12"></line>
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
</svg>
</symbol>
<symbol id="svg-moon" viewBox="0 0 24 24">
<title>Dark mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
<path stroke="none" d="M0 0h24v24H0z" fill="none" />
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
</svg>
</symbol>
<symbol id="svg-sun-with-moon" viewBox="0 0 24 24">
<title>Auto light/dark, in light mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
class="icon-custom-derived-from-feather-sun-and-tabler-moon">
<path style="opacity: 50%" d="M 5.411 14.504 C 5.471 14.504 5.532 14.504 5.591 14.504 C 3.639 16.319 4.383 19.569 6.931 20.352 C 7.693 20.586 8.512 20.551 9.25 20.252 C 8.023 23.207 4.056 23.725 2.11 21.184 C 0.166 18.642 1.702 14.949 4.874 14.536 C 5.051 14.512 5.231 14.5 5.411 14.5 L 5.411 14.504 Z"/>
<line x1="14.5" y1="3.25" x2="14.5" y2="1.25"/>
<line x1="14.5" y1="15.85" x2="14.5" y2="17.85"/>
<line x1="10.044" y1="5.094" x2="8.63" y2="3.68"/>
<line x1="19" y1="14.05" x2="20.414" y2="15.464"/>
<line x1="8.2" y1="9.55" x2="6.2" y2="9.55"/>
<line x1="20.8" y1="9.55" x2="22.8" y2="9.55"/>
<line x1="10.044" y1="14.006" x2="8.63" y2="15.42"/>
<line x1="19" y1="5.05" x2="20.414" y2="3.636"/>
<circle cx="14.5" cy="9.55" r="3.6"/>
</svg>
</symbol>
<symbol id="svg-moon-with-sun" viewBox="0 0 24 24">
<title>Auto light/dark, in dark mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
class="icon-custom-derived-from-feather-sun-and-tabler-moon">
<path d="M 8.282 7.007 C 8.385 7.007 8.494 7.007 8.595 7.007 C 5.18 10.184 6.481 15.869 10.942 17.24 C 12.275 17.648 13.706 17.589 15 17.066 C 12.851 22.236 5.91 23.143 2.505 18.696 C -0.897 14.249 1.791 7.786 7.342 7.063 C 7.652 7.021 7.965 7 8.282 7 L 8.282 7.007 Z"/>
<line style="opacity: 50%" x1="18" y1="3.705" x2="18" y2="2.5"/>
<line style="opacity: 50%" x1="18" y1="11.295" x2="18" y2="12.5"/>
<line style="opacity: 50%" x1="15.316" y1="4.816" x2="14.464" y2="3.964"/>
<line style="opacity: 50%" x1="20.711" y1="10.212" x2="21.563" y2="11.063"/>
<line style="opacity: 50%" x1="14.205" y1="7.5" x2="13.001" y2="7.5"/>
<line style="opacity: 50%" x1="21.795" y1="7.5" x2="23" y2="7.5"/>
<line style="opacity: 50%" x1="15.316" y1="10.184" x2="14.464" y2="11.036"/>
<line style="opacity: 50%" x1="20.711" y1="4.789" x2="21.563" y2="3.937"/>
<circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/>
</svg>
</symbol>
<symbol id="svg-pencil" viewBox="0 0 24 24">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code">
<path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" />
<path d="M13.5 6.5l4 4" />
<path d="M20 21l2 -2l-2 -2" />
<path d="M17 17l-2 2l2 2" />
</svg>
</symbol>
<symbol id="svg-eye" viewBox="0 0 24 24">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code">
<path stroke="none" d="M0 0h24v24H0z" fill="none" />
<path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" />
<path
d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" />
<path d="M20 21l2 -2l-2 -2" />
<path d="M17 17l-2 2l2 2" />
</svg>
</symbol>
</svg>
<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
<label class="overlay sidebar-overlay" for="__navigation">
<div class="visually-hidden">Hide navigation sidebar</div>
</label>
<label class="overlay toc-overlay" for="__toc">
<div class="visually-hidden">Hide table of contents sidebar</div>
</label>
<a class="skip-to-content muted-link" href="#furo-main-content">Skip to content</a>
<div class="page">
<header class="mobile-header">
<div class="header-left">
<label class="nav-overlay-icon" for="__navigation">
<div class="visually-hidden">Toggle site navigation sidebar</div>
<i class="icon"><svg><use href="#svg-menu"></use></svg></i>
</label>
</div>
<div class="header-center">
<a href="../index.html"><div class="brand">pip documentation v25.1.1</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
<button class="theme-toggle">
<div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
<svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
<svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
<svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
<svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
</button>
</div>
<label class="toc-overlay-icon toc-header-icon" for="__toc">
<div class="visually-hidden">Toggle table of contents sidebar</div>
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
</label>
</div>
</header>
<aside class="sidebar-drawer">
<div class="sidebar-container">
<div class="sidebar-sticky"><a class="sidebar-brand" href="../index.html">
<span class="sidebar-brand-text">pip documentation v25.1.1</span>
</a><form class="sidebar-search-container" method="get" action="../search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
<input type="hidden" name="check_keywords" value="yes">
<input type="hidden" name="area" value="default">
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../getting-started.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user_guide.html">User Guide</a></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="../topics/index.html">Topic Guides</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Topic Guides</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l2"><a class="reference internal" href="../topics/authentication.html">Authentication</a></li>
<li class="toctree-l2"><a class="reference internal" href="../topics/caching.html">Caching</a></li>
<li class="toctree-l2"><a class="reference internal" href="../topics/configuration.html">Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../topics/dependency-resolution.html">Dependency Resolution</a></li>
<li class="toctree-l2"><a class="reference internal" href="../topics/more-dependency-resolution.html">More on Dependency Resolution</a></li>
<li class="toctree-l2"><a class="reference internal" href="../topics/https-certificates.html">HTTPS Certificates</a></li>
<li class="toctree-l2"><a class="reference internal" href="../topics/local-project-installs.html">Local project installs</a></li>
<li class="toctree-l2"><a class="reference internal" href="../topics/repeatable-installs.html">Repeatable Installs</a></li>
<li class="toctree-l2"><a class="reference internal" href="../topics/secure-installs.html">Secure installs</a></li>
<li class="toctree-l2"><a class="reference internal" href="../topics/vcs-support.html">VCS Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../topics/python-option.html">Managing a different Python interpreter</a></li>
<li class="toctree-l2"><a class="reference internal" href="../topics/workflow.html">Pip is not a workflow management tool</a></li>
</ul>
</li>
<li class="toctree-l1 has-children"><a class="reference internal" href="../reference/index.html">Reference</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Reference</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l2 has-children"><a class="reference internal" href="../reference/build-system/index.html">Build System Interface</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" role="switch" type="checkbox"/><label for="toctree-checkbox-3"><div class="visually-hidden">Toggle navigation of Build System Interface</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../reference/build-system/pyproject-toml.html"><code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="../reference/build-system/setup-py.html"><code class="docutils literal notranslate"><span class="pre">setup.py</span></code> (legacy)</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../reference/requirement-specifiers.html">Requirement Specifiers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../reference/requirements-file-format.html">Requirements File Format</a></li>
<li class="toctree-l2"><a class="reference internal" href="../reference/installation-report.html">Installation Report</a></li>
<li class="toctree-l2"><a class="reference internal" href="../reference/inspect-report.html"><code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">inspect</span></code> JSON output specification</a></li>
</ul>
</li>
<li class="toctree-l1 has-children"><a class="reference internal" href="../cli/index.html">Commands</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" role="switch" type="checkbox"/><label for="toctree-checkbox-4"><div class="visually-hidden">Toggle navigation of Commands</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip.html">pip</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip_install.html">pip install</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip_uninstall.html">pip uninstall</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip_inspect.html">pip inspect</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip_list.html">pip list</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip_show.html">pip show</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip_freeze.html">pip freeze</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip_check.html">pip check</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip_lock.html">pip lock</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip_download.html">pip download</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip_wheel.html">pip wheel</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip_hash.html">pip hash</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip_search.html">pip search</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip_index.html">pip index</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip_cache.html">pip cache</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip_config.html">pip config</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cli/pip_debug.html">pip debug</a></li>
</ul>
</li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Project</span></p>
<ul class="current">
<li class="toctree-l1 current has-children"><a class="reference internal" href="index.html">Development</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" role="switch" type="checkbox"/><label for="toctree-checkbox-5"><div class="visually-hidden">Toggle navigation of Development</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="getting-started.html">Getting Started</a></li>
<li class="toctree-l2"><a class="reference internal" href="contributing.html">Contributing</a></li>
<li class="toctree-l2"><a class="reference internal" href="ci.html">Continuous Integration</a></li>
<li class="toctree-l2 current current-page"><a class="current reference internal" href="#">Issue Triage</a></li>
<li class="toctree-l2 has-children"><a class="reference internal" href="architecture/index.html">Architecture of pip’s internals</a><input class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" role="switch" type="checkbox"/><label for="toctree-checkbox-6"><div class="visually-hidden">Toggle navigation of Architecture of pip’s internals</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="architecture/overview.html">Broad functionality overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="architecture/anatomy.html">Repository anatomy & directory structure</a></li>
<li class="toctree-l3"><a class="reference internal" href="architecture/configuration-files.html">Configuration File Handling</a></li>
<li class="toctree-l3"><a class="reference internal" href="architecture/package-finding.html">Finding and choosing files (<code class="docutils literal notranslate"><span class="pre">index</span></code> and <code class="docutils literal notranslate"><span class="pre">PackageFinder</span></code>)</a></li>
<li class="toctree-l3"><a class="reference internal" href="architecture/command-line-interface.html">Command Line Interface</a></li>
<li class="toctree-l3"><a class="reference internal" href="architecture/upgrade-options.html">Options that control the installation process</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="release-process.html">Release process</a></li>
<li class="toctree-l2"><a class="reference internal" href="vendoring-policy.html">Vendoring Policy</a></li>
</ul>
</li>
<li class="toctree-l1 has-children"><a class="reference internal" href="../ux-research-design/index.html">UX Research & Design</a><input class="toctree-checkbox" id="toctree-checkbox-7" name="toctree-checkbox-7" role="switch" type="checkbox"/><label for="toctree-checkbox-7"><div class="visually-hidden">Toggle navigation of UX Research & Design</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l2"><a class="reference internal" href="../ux-research-design/contribute.html">How to Contribute</a></li>
<li class="toctree-l2"><a class="reference internal" href="../ux-research-design/guidance.html">UX Guidance</a></li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../ux-research-design/research-results/index.html">UX Research Results</a><input class="toctree-checkbox" id="toctree-checkbox-8" name="toctree-checkbox-8" role="switch" type="checkbox"/><label for="toctree-checkbox-8"><div class="visually-hidden">Toggle navigation of UX Research Results</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../ux-research-design/research-results/about-our-users.html">About pip’s Users</a></li>
<li class="toctree-l3"><a class="reference internal" href="../ux-research-design/research-results/mental-models.html">How Users Understand pip</a></li>
<li class="toctree-l3"><a class="reference internal" href="../ux-research-design/research-results/users-and-security.html">How pip users think about security</a></li>
<li class="toctree-l3"><a class="reference internal" href="../ux-research-design/research-results/ci-cd.html">How pip is used in interactive environments (i.e. CI, CD)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../ux-research-design/research-results/personas.html">pip Personas</a></li>
<li class="toctree-l3"><a class="reference internal" href="../ux-research-design/research-results/prioritizing-features.html">Prioritizing pip Features</a></li>
<li class="toctree-l3"><a class="reference internal" href="../ux-research-design/research-results/override-conflicting-dependencies.html">Providing an override to install packages with conflicting dependencies</a></li>
<li class="toctree-l3"><a class="reference internal" href="../ux-research-design/research-results/pip-force-reinstall.html">pip --force-reinstall</a></li>
<li class="toctree-l3"><a class="reference internal" href="../ux-research-design/research-results/pip-search.html">pip search</a></li>
<li class="toctree-l3"><a class="reference internal" href="../ux-research-design/research-results/pip-upgrade-conflict.html">pip Upgrade Conflict</a></li>
<li class="toctree-l3"><a class="reference internal" href="../ux-research-design/research-results/improving-pips-documentation.html">Improving pip’s Documentation</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../news.html">Changelog</a></li>
<li class="toctree-l1"><a class="reference external" href="https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md">Code of Conduct</a></li>
<li class="toctree-l1"><a class="reference external" href="https://github.com/pypa/pip">GitHub</a></li>
</ul>
</div>
</div>
</div>
</div>
</aside>
<div class="main">
<div class="content">
<div class="article-container">
<a href="#" class="back-to-top muted-link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
<path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
</svg>
<span>Back to top</span>
</a>
<div class="content-icon-container">
<div class="view-this-page">
<a class="muted-link" href="../_sources/development/issue-triage.md.txt" title="View this page">
<svg><use href="#svg-eye"></use></svg>
<span class="visually-hidden">View this page</span>
</a>
</div>
<div class="theme-toggle-container theme-toggle-content">
<button class="theme-toggle">
<div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
<svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
<svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
<svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
<svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
</button>
</div>
<label class="toc-overlay-icon toc-content-icon" for="__toc">
<div class="visually-hidden">Toggle table of contents sidebar</div>
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
</label>
</div>
<article role="main" id="furo-main-content">
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>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
<a class="reference external" href="https://github.com/pypa/pip/issues/6583">tracking issue</a>, or
just submit a pull request and mention it in that tracking issue.</p>
</div>
<section id="issue-triage">
<h1>Issue Triage<a class="headerlink" href="#issue-triage" title="Link to this heading">¶</a></h1>
<p>This serves as an introduction to issue tracking in pip as well as
how to help triage reported issues.</p>
<section id="issue-tracker">
<h2>Issue Tracker<a class="headerlink" href="#issue-tracker" title="Link to this heading">¶</a></h2>
<p>The <a class="reference external" href="https://github.com/pypa/pip/issues">pip issue tracker</a> is hosted on
GitHub alongside the project.</p>
<p>Currently, the issue tracker is used for bugs, feature requests, and general
user support.</p>
<p>In the pip issue tracker, we make use of labels and milestones to organize and
track work.</p>
<section id="labels">
<h3>Labels<a class="headerlink" href="#labels" title="Link to this heading">¶</a></h3>
<p>Issue labels are used to:</p>
<ol class="arabic simple">
<li><p>Categorize issues</p></li>
<li><p>Provide status information for contributors and reporters</p></li>
<li><p>Help contributors find tasks to work on</p></li>
</ol>
<p>The current set of labels are divided into several categories identified by
prefix:</p>
<dl class="simple myst">
<dt><strong>C - Category</strong></dt><dd><p>which area of <code class="docutils literal notranslate"><span class="pre">pip</span></code> functionality a feature request or issue is related to</p>
</dd>
</dl>
<p><strong>K - Kind</strong>
<strong>O - Operating System</strong>
: for issues that are OS-specific</p>
<dl class="simple myst">
<dt><strong>P - Project/Platform</strong></dt><dd><p>related to something external to <code class="docutils literal notranslate"><span class="pre">pip</span></code></p>
</dd>
<dt><strong>R - Resolution</strong></dt><dd><p>no more discussion is really needed, an action has been identified and the
issue is waiting or closed</p>
</dd>
<dt><strong>S - State</strong></dt><dd><p>for some automatic labels and other indicators that work is needed</p>
</dd>
<dt><strong>type</strong></dt><dd><p>the role or flavor of an issue</p>
</dd>
</dl>
<p>The specific labels falling into each category have a description that can be
seen on the <a class="reference external" href="https://github.com/pypa/pip/labels">Labels</a> page.</p>
<p>In addition, there are several standalone labels:</p>
<dl class="simple myst">
<dt><strong>good first issue</strong></dt><dd><p>this label marks an issue as beginner-friendly and shows up in banners that
GitHub displays for first-time visitors to the repository</p>
</dd>
<dt><strong>triage</strong></dt><dd><p>default label given to issues when they are created</p>
</dd>
<dt><strong>trivial</strong></dt><dd><p>special label for pull requests that removes the
<a class="reference internal" href="contributing.html#choosing-news-entry-type"><span class="std std-ref">news file requirement</span></a></p>
</dd>
<dt><strong>needs rebase or merge</strong></dt><dd><p>this is a special label used by BrownTruck to mark PRs that have merge
conflicts</p>
</dd>
</dl>
</section>
<section id="automation">
<h3>Automation<a class="headerlink" href="#automation" title="Link to this heading">¶</a></h3>
<p>There are several helpers to manage issues and pull requests.</p>
<p>Issues created on the issue tracker are automatically given the
<code class="docutils literal notranslate"><span class="pre">triage</span></code> label by the
<a class="reference external" href="https://github.com/apps/triage-new-issues">triage-new-issues</a>
bot. The label is automatically removed when another label is added.</p>
<p>When an issue needs feedback from the author we can label it with
<code class="docutils literal notranslate"><span class="pre">S:</span> <span class="pre">awaiting</span> <span class="pre">response</span></code>. When the author responds, the
<a class="reference external" href="https://github.com/apps/no-response">no-response</a> bot removes the label.</p>
<p>After an issue has been closed for 30 days, the
<a class="reference external" href="https://github.com/apps/lock">lock</a> bot locks the issue and adds the
<code class="docutils literal notranslate"><span class="pre">S:</span> <span class="pre">auto-locked</span></code> 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.</p>
</section>
</section>
<section id="triage-issues">
<h2>Triage Issues<a class="headerlink" href="#triage-issues" title="Link to this heading">¶</a></h2>
<p>Users can make issues for a number of reasons:</p>
<ol class="arabic simple">
<li><p>Suggestions about pip features that could be added or improved</p></li>
<li><p>Problems using pip</p></li>
<li><p>Concerns about pip usability</p></li>
<li><p>General packaging problems to be solved with pip</p></li>
<li><p>Problems installing or using Python packages</p></li>
<li><p>Problems managing virtual environments</p></li>
<li><p>Problems managing Python installations</p></li>
</ol>
<p>To triage issues means to identify what kind of issue is happening and</p>
<ul class="simple">
<li><p>confirm bugs</p></li>
<li><p>provide support</p></li>
<li><p>discuss and design around the uses of the tool</p></li>
</ul>
<p>Specifically, to address an issue:</p>
<ol class="arabic simple">
<li><p>Read issue title</p></li>
<li><p>Scan issue description</p></li>
<li><p>Ask questions</p></li>
<li><p>If time is available, try to reproduce</p></li>
<li><p>Search for or remember related issues and link to them</p></li>
<li><p>Identify an appropriate area of concern (if applicable)</p></li>
</ol>
<p>Keep in mind that all communication is happening with other people and
should be done with respect per the
<a class="reference external" href="https://www.pypa.io/en/latest/code-of-conduct/">Code of Conduct</a>.</p>
<p>The lifecycle of an issue (bug or support) generally looks like:</p>
<ol class="arabic simple">
<li><p>waiting for triage (marked with label <code class="docutils literal notranslate"><span class="pre">triage</span></code>)</p></li>
<li><p>confirming issue - some discussion with the user, gathering
details, trying to reproduce the issue (may be marked with a specific
category, <code class="docutils literal notranslate"><span class="pre">S:</span> <span class="pre">awaiting-response</span></code>, <code class="docutils literal notranslate"><span class="pre">S:</span> <span class="pre">discussion-needed</span></code>, or
<code class="docutils literal notranslate"><span class="pre">S:</span> <span class="pre">need-repro</span></code>)</p></li>
<li><p>confirmed - the issue is pretty consistently reproducible in a
straightforward way, or a mechanism that could be causing the issue has been
identified</p></li>
<li><p>awaiting fix - the fix is identified and no real discussion on the issue
is needed, should be marked <code class="docutils literal notranslate"><span class="pre">R:</span> <span class="pre">awaiting</span> <span class="pre">PR</span></code></p></li>
<li><p>closed - can be for several reasons</p>
<ul class="simple">
<li><p>fixed</p></li>
<li><p>could not be reproduced, no more details could be obtained, and no
progress can be made</p></li>
<li><p>actual issue was with another project or related to system
configuration and pip cannot (or will not) be adapted for it</p></li>
</ul>
</li>
</ol>
<section id="requesting-information">
<h3>Requesting information<a class="headerlink" href="#requesting-information" title="Link to this heading">¶</a></h3>
<p>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:</p>
<ul class="simple">
<li><p>pip debug: <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">debug</span></code></p></li>
<li><p>pip version: <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">-V</span></code></p></li>
<li><p>Python version: <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-VV</span></code></p></li>
<li><p>Python path: <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-c</span> <span class="pre">'import</span> <span class="pre">sys;</span> <span class="pre">print(sys.executable)'</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">python</span></code> on <code class="docutils literal notranslate"><span class="pre">PATH</span></code>: Unix: <code class="docutils literal notranslate"><span class="pre">which</span> <span class="pre">python</span></code>; Windows: <code class="docutils literal notranslate"><span class="pre">where</span> <span class="pre">python</span></code></p></li>
<li><p>Python as resolved by the shell: <code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">python</span></code></p></li>
<li><p>Origin of pip (get-pip.py, OS-level package manager, ensurepip, manual
installation)</p></li>
<li><p>Using a virtual environment (with <code class="docutils literal notranslate"><span class="pre">--system-site-packages</span></code>?)</p></li>
<li><p>Using a conda environment</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">PATH</span></code> environment variable</p></li>
<li><p>Network situation (e.g. airgapped environment, firewalls)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--verbose</span></code> output of a failing command</p></li>
<li><p>(Unix) <code class="docutils literal notranslate"><span class="pre">strace</span></code> output 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…)</p></li>
<li><p>(Windows)
<a class="reference external" href="https://docs.microsoft.com/en-us/sysinternals/downloads/procmon">procmon</a>
output during a failing command
(<a class="reference external" href="https://github.com/pypa/pip/issues/6814#issuecomment-516611389">example request</a>)</p></li>
<li><p>Listing of files relevant to the issue (e.g. <code class="docutils literal notranslate"><span class="pre">ls</span> <span class="pre">-l</span> <span class="pre">venv/lib/pythonX.Y/problem-package.dist-info/</span></code>)</p></li>
<li><p>whether the unexpected behavior ever worked as expected - if so then what
were the details of the setup (same information as above)</p></li>
</ul>
<p>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.</p>
</section>
<section id="reproducing-issues">
<h3>Reproducing issues<a class="headerlink" href="#reproducing-issues" title="Link to this heading">¶</a></h3>
<p>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:</p>
<ol class="arabic simple">
<li><p>If it is a pip bug, then any fix will need tests - a good reproducer
is most of the way towards that.</p></li>
<li><p>If it is not reproducible using the provided instructions, that helps
rule out a lot of possible causes.</p></li>
<li><p>A clear set of instructions is an easy way to get on the same page as
someone reporting an issue.</p></li>
</ol>
<p>The best way to reproduce an issue is with a script.</p>
<p>A script can be copied into a file and executed, whereas shell output
has to be manually copied a line at a time.</p>
<p>Scripts to reproduce issues should be:</p>
<ul class="simple">
<li><p>portable (few/no assumptions about the system, other that it being Unix or Windows as applicable)</p></li>
<li><p>non-destructive</p></li>
<li><p>convenient</p></li>
<li><p>require little/no setup on the part of the runner</p></li>
</ul>
<p>Examples:</p>
<ul class="simple">
<li><p>creating and installing multiple wheels with different versions
(<a class="reference external" href="https://github.com/pypa/pip/issues/4331#issuecomment-520156471">link</a>)</p></li>
<li><p>using a small web server for authentication errors
(<a class="reference external" href="https://github.com/pypa/pip/issues/2920#issuecomment-508953118">link</a>)</p></li>
<li><p>using docker to test system or global configuration-related issues
(<a class="reference external" href="https://github.com/pypa/pip/issues/5533#issuecomment-520159896">link</a>)</p></li>
<li><p>using docker to test special filesystem permission/configurations
(<a class="reference external" href="https://github.com/pypa/pip/issues/6364#issuecomment-507074729">link</a>)</p></li>
<li><p>using docker for global installation with get-pip
(<a class="reference external" href="https://github.com/pypa/pip/issues/6498#issuecomment-513501112">link</a>)</p></li>
<li><p>get-pip on system with no <code class="docutils literal notranslate"><span class="pre">/usr/lib64</span></code>
(<a class="reference external" href="https://github.com/pypa/pip/issues/5379#issuecomment-515270576">link</a>)</p></li>
<li><p>reproducing with <code class="docutils literal notranslate"><span class="pre">pip</span></code> from current development branch
(<a class="reference external" href="https://github.com/pypa/pip/issues/6707#issue-467770959">link</a>)</p></li>
</ul>
</section>
<section id="reaching-resolution">
<h3>Reaching resolution<a class="headerlink" href="#reaching-resolution" title="Link to this heading">¶</a></h3>
<p>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:</p>
<ol class="arabic simple">
<li><p>Unless the issue is very old and the user doesn’t seem active, wait for
confirmation before closing the issue</p></li>
<li><p>Direct the user to the most appropriate forum for their questions:</p>
<ul class="simple">
<li><p>For Ubuntu, <a class="reference external" href="https://askubuntu.com/">askubuntu</a></p></li>
<li><p>For Other linuxes/unixes, <a class="reference external" href="https://serverfault.com/">serverfault</a></p></li>
<li><p>For network connectivity issues,
<a class="reference external" href="https://serverfault.com/">serverfault</a></p></li>
</ul>
</li>
<li><p>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.</p></li>
<li><p>A user may be having trouble installing a package, where the package
<code class="docutils literal notranslate"><span class="pre">setup.py</span></code> or 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.</p></li>
<li><p>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.</p></li>
<li><p>For general discussion on Python packaging:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/pypa/packaging-problems">pypa/packaging</a></p></li>
<li><p><a class="reference external" href="https://discuss.python.org/c/packaging">discuss.python.org/packaging</a></p></li>
</ul>
</li>
</ol>
</section>
<section id="closing-issues">
<h3>Closing issues<a class="headerlink" href="#closing-issues" title="Link to this heading">¶</a></h3>
<p>An issue may be considered resolved and closed when:</p>
<ul class="simple">
<li><p>for each possible improvement or problem represented in the issue
discussion:</p>
<ul>
<li><p>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.</p>
<ul>
<li><p>PEP updates (with a corresponding issue in
<a class="reference external" href="https://github.com/python/peps">python/peps</a>)</p></li>
<li><p>already tracked by another issue</p></li>
</ul>
</li>
<li><p>A project-specific issue has been identified and the issue no
longer occurs as of the latest commit on the main branch.</p></li>
</ul>
</li>
<li><p>An enhancement or feature request no longer has a proponent and the maintainers
don’t think it’s worth keeping open.</p></li>
<li><p>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)</p></li>
<li><p>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.</p></li>
</ul>
</section>
</section>
<section id="common-issues">
<h2>Common issues<a class="headerlink" href="#common-issues" title="Link to this heading">¶</a></h2>
<ol class="arabic simple">
<li><p>network-related issues - any issue involving retries, address lookup, or
anything like that are typically network issues.</p></li>
<li><p>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:</p>
<ol class="arabic simple">
<li><p>Not being able to find installed packages</p></li>
<li><p>basic libraries not able to be found, fundamental OS components missing</p></li>
<li><p>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. <code class="docutils literal notranslate"><span class="pre">dpkg</span> <span class="pre">-S</span></code>.</p></li>
</ol>
</li>
</ol>
</section>
<section id="for-issues-caused-by-changes-by-redistributors">
<h2>For issues caused by changes by redistributors<a class="headerlink" href="#for-issues-caused-by-changes-by-redistributors" title="Link to this heading">¶</a></h2>
<p>Certain issues are caused by patches that redistributors of Python/pip
make to Python/pip.</p>
<p>Certain redistributors have shared preferred wording to redirect users
to their issue trackers.</p>
<p>Fedora, RHEL, CentOS (and probably other derivatives – Rocky, Scientific, CloudLinux):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>This issue looks like it's caused by changes that Fedora or Red Hat
made in their pip packaging. Please file a Fedora bug at
https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=python-pip
cc @encukou @hroncok
</pre></div>
</div>
<p>Debian:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>This issue looks like it's caused by changes that Debian made in
their pip packaging. Please file a bug with Debian, with
`reportbug python3-pip` [Docs](https://www.debian.org/Bugs/Reporting).
You can link to this issue in your bug report.
In the meantime, you may be able to work-around your issue by upgrading
pip inside your virtualenv: `python -m pip install -U pip`
</pre></div>
</div>
<p>Ubuntu:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>This issue looks like it's caused by changes that Ubuntu made in
their pip packaging. Please file a bug with Ubuntu, with
`ubuntu-bug python3-pip` [Docs](https://help.ubuntu.com/community/ReportingBugs).
You can link to this issue in your bug report.
In the meantime, you may be able to work-around your issue by upgrading
pip inside your virtualenv: `python -m pip install -U pip`
</pre></div>
</div>
</section>
</section>
</article>
</div>
<footer>
<div class="related-pages">
<a class="next-page" href="architecture/index.html">
<div class="page-info">
<div class="context">
<span>Next</span>
</div>
<div class="title">Architecture of pip’s internals</div>
</div>
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
</a>
<a class="prev-page" href="ci.html">
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
<div class="page-info">
<div class="context">
<span>Previous</span>
</div>
<div class="title">Continuous Integration</div>
</div>
</a>
</div>
<div class="bottom-of-page">
<div class="left-details">
<div class="copyright">
<a href="../copyright.html">Copyright</a> © The pip developers
</div>
Made with <a href="https://www.sphinx-doc.org/">Sphinx</a> and <a class="muted-link" href="https://pradyunsg.me">@pradyunsg</a>'s
<a href="https://github.com/pradyunsg/furo">Furo</a>
</div>
<div class="right-details">
</div>
</div>
</footer>
</div>
<aside class="toc-drawer">
<div class="toc-sticky toc-scroll">
<div class="toc-title-container">
<span class="toc-title">
On this page
</span>
</div>
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">Issue Triage</a><ul>
<li><a class="reference internal" href="#issue-tracker">Issue Tracker</a><ul>
<li><a class="reference internal" href="#labels">Labels</a></li>
<li><a class="reference internal" href="#automation">Automation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#triage-issues">Triage Issues</a><ul>
<li><a class="reference internal" href="#requesting-information">Requesting information</a></li>
<li><a class="reference internal" href="#reproducing-issues">Reproducing issues</a></li>
<li><a class="reference internal" href="#reaching-resolution">Reaching resolution</a></li>
<li><a class="reference internal" href="#closing-issues">Closing issues</a></li>
</ul>
</li>
<li><a class="reference internal" href="#common-issues">Common issues</a></li>
<li><a class="reference internal" href="#for-issues-caused-by-changes-by-redistributors">For issues caused by changes by redistributors</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</aside>
</div>
</div><script src="../_static/documentation_options.js?v=22103397"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script type="module" src="../_static/scripts/furo.js?v=d32f1409"></script>
<script src="../_static/clipboard.min.js?v=66b4909c"></script>
<script src="../_static/copybutton.js?v=80126f2a"></script>
<script src="../_static/tabs.js?v=3ee01567"></script>
</body>
</html>