<!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="Continuous Integration" href="ci.html" /><link rel="prev" title="Getting Started" href="getting-started.html" />
<!-- Generated with Sphinx 8.1.3 and Furo 2024.08.06 -->
<title>Contributing - 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 current current-page"><a class="current reference internal" href="#">Contributing</a></li>
<li class="toctree-l2"><a class="reference internal" href="ci.html">Continuous Integration</a></li>
<li class="toctree-l2"><a class="reference internal" href="issue-triage.html">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/contributing.rst.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">
<section id="contributing">
<h1>Contributing<a class="headerlink" href="#contributing" title="Link to this heading">¶</a></h1>
<section id="pip-s-internals">
<h2>Pip’s internals<a class="headerlink" href="#pip-s-internals" title="Link to this heading">¶</a></h2>
<p>We have an in-progress guide to the
<a class="reference internal" href="architecture/index.html#architecture-pip-internals"><span class="std std-ref">Architecture of pip’s internals</span></a>. It might be helpful as you dive in.</p>
</section>
<section id="submitting-pull-requests">
<h2>Submitting Pull Requests<a class="headerlink" href="#submitting-pull-requests" title="Link to this heading">¶</a></h2>
<p>Submit pull requests against the <code class="docutils literal notranslate"><span class="pre">main</span></code> branch, providing a good
description of what you’re doing and why. You must have legal permission to
distribute any code you contribute to pip and it must be available under the
MIT License.</p>
<p>Provide tests that cover your changes and run the tests locally first. pip
<a class="reference internal" href="../installation.html#compatibility-requirements"><span class="std std-ref">supports</span></a> multiple Python versions and
operating systems. Any pull request must consider and work on all these
platforms.</p>
<p>Pull requests should be small to facilitate easier review. Keep them
self-contained, and limited in scope. <a class="reference external" href="https://www.kessler.de/prd/smartbear/BestPracticesForPeerCodeReview.pdf">Studies have shown</a> that review quality
falls off as patch size grows. Sometimes this will result in many small PRs to
land a single large feature. In particular, pull requests must not be treated
as “feature branches”, with ongoing development work happening within the PR.
Instead, the feature should be broken up into smaller, independent parts which
can be reviewed and merged individually.</p>
<p>Additionally, avoid including “cosmetic” changes to code that
is unrelated to your change, as these make reviewing the PR more difficult.
Examples include re-flowing text in comments or documentation, or adding or
removing blank lines or whitespace within lines. Such changes can be made
separately, as a “formatting cleanup” PR, if needed.</p>
</section>
<section id="automated-testing">
<h2>Automated Testing<a class="headerlink" href="#automated-testing" title="Link to this heading">¶</a></h2>
<p>All pull requests and merges to ‘main’ branch are tested using <a class="reference external" href="https://github.com/features/actions">GitHub
Actions</a> based on our <a class="reference external" href="https://github.com/pypa/pip/blob/main/.github/workflows">.github/workflows</a> files. More details about pip’s
Continuous Integration can be found in the <a class="reference external" href="https://pip.pypa.io/en/latest/development/ci/">CI Documentation</a></p>
<p>You can find the status and results to the CI runs for your PR on GitHub’s web
UI for the pull request. You can also find links to the CI services’ pages for
the specific builds in the form of “Details” links, in case the CI run fails
and you wish to view the output.</p>
<p>To trigger CI to run again for a pull request, you can close and open the pull
request or submit another change to the pull request. If needed, project
maintainers can manually trigger a restart of a job/build.</p>
<p>To understand the broader software architecture around dependency
resolution in pip, and how we automatically test this functionality,
see <a class="reference external" href="https://pradyunsg.me/blog/2020/03/27/pip-resolver-testing/">Testing the next-gen pip dependency resolver</a>.</p>
</section>
<section id="news-entries">
<h2>NEWS Entries<a class="headerlink" href="#news-entries" title="Link to this heading">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">NEWS.rst</span></code> file is managed using <a class="reference external" href="https://pypi.org/project/towncrier/">towncrier</a> and all non trivial changes
must be accompanied by a news entry.</p>
<p>To add an entry to the news file, first you need to have created an issue
describing the change you want to make. A Pull Request itself <em>may</em> function as
such, but it is preferred to have a dedicated issue (for example, in case the
PR ends up rejected due to code quality reasons).</p>
<p>Once you have an issue or pull request, you take the number and you create a
file inside of the <code class="docutils literal notranslate"><span class="pre">news/</span></code> directory, named after that issue number with a
“type” of <code class="docutils literal notranslate"><span class="pre">removal</span></code>, <code class="docutils literal notranslate"><span class="pre">feature</span></code>, <code class="docutils literal notranslate"><span class="pre">bugfix</span></code>, or <code class="docutils literal notranslate"><span class="pre">doc</span></code> associated with it.</p>
<p>If your issue or PR number is <code class="docutils literal notranslate"><span class="pre">1234</span></code> and this change is fixing a bug,
then you would create a file <code class="docutils literal notranslate"><span class="pre">news/1234.bugfix.rst</span></code>. PRs can span multiple
categories by creating multiple files (for instance, if you added a feature and
deprecated/removed the old feature at the same time, you would create
<code class="docutils literal notranslate"><span class="pre">news/NNNN.feature.rst</span></code> and <code class="docutils literal notranslate"><span class="pre">news/NNNN.removal.rst</span></code>).</p>
<p>If a PR touches multiple issues/PRs, you may create a file for each of them
with the exact same contents and Towncrier will deduplicate them.</p>
<section id="contents-of-a-news-entry">
<h3>Contents of a NEWS entry<a class="headerlink" href="#contents-of-a-news-entry" title="Link to this heading">¶</a></h3>
<p>The contents of this file are reStructuredText formatted text that
will be used as the content of the news file entry. You do not need to
reference the issue or PR numbers in the entry, since <code class="docutils literal notranslate"><span class="pre">towncrier</span></code>
will automatically add a reference to all of the affected issues when
rendering the NEWS file. There must be a newline at the end of the file.</p>
<p>In order to maintain a consistent style in the <code class="docutils literal notranslate"><span class="pre">NEWS.rst</span></code> file, it is
preferred to keep the news entry to the point, in sentence case, shorter than
80 characters and in an imperative tone -- an entry should complete the sentence
“This change will …”. In rare cases, where one line is not enough, use a
summary line in an imperative tone followed by a blank line separating it
from a description of the feature/change in one or more paragraphs, each wrapped
at 80 characters. Remember that a news entry is meant for end users and should
only contain details relevant to an end user.</p>
</section>
<section id="choosing-the-type-of-news-entry">
<span id="choosing-news-entry-type"></span><h3>Choosing the type of NEWS entry<a class="headerlink" href="#choosing-the-type-of-news-entry" title="Link to this heading">¶</a></h3>
<p>A trivial change is anything that does not warrant an entry in the news file.
Some examples are: Code refactors that don’t change anything as far as the
public is concerned, typo fixes, white space modification, etc. To mark a PR
as trivial a contributor simply needs to add a randomly named, empty file to
the <code class="docutils literal notranslate"><span class="pre">news/</span></code> directory with the extension of <code class="docutils literal notranslate"><span class="pre">.trivial.rst</span></code>. If you are on a
POSIX like operating system, one can be added by running
<code class="docutils literal notranslate"><span class="pre">touch</span> <span class="pre">news/$(uuidgen).trivial.rst</span></code>. On Windows, the same result can be
achieved in Powershell using <code class="docutils literal notranslate"><span class="pre">New-Item</span> <span class="pre">"news/$([guid]::NewGuid()).trivial.rst"</span></code>.
Core committers may also add a “skip news” label to the PR which will accomplish
the same thing.</p>
<p>Upgrading, removing, or adding a new vendored library gets a special mention
using a <code class="docutils literal notranslate"><span class="pre">news/<library>.vendor.rst</span></code> file. This is in addition to any features,
bugfixes, or other kinds of news that pulling in this library may have. This
uses the library name as the key so that updating the same library twice doesn’t
produce two news file entries.</p>
<p>Changes to the processes, policies, or other non code related changed that are
otherwise notable can be done using a <code class="docutils literal notranslate"><span class="pre">news/<name>.process.rst</span></code> file. This is
not typically used, but can be used for things like changing version schemes,
updating deprecation policy, etc.</p>
</section>
</section>
<section id="updating-your-branch">
<h2>Updating your branch<a class="headerlink" href="#updating-your-branch" title="Link to this heading">¶</a></h2>
<p>As you work, you might need to update your local main branch up-to-date with
the <code class="docutils literal notranslate"><span class="pre">main</span></code> branch in the main pip repository, which moves forward as the
maintainers merge pull requests. Most people working on the project use the
following workflow.</p>
<p>This assumes that you have Git configured so that when you run the following
command:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">git remote -v</span>
</pre></div>
</div>
<p>Your output looks like this:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">origin https://github.com/USERNAME/pip.git (fetch)</span>
<span class="go">origin https://github.com/USERNAME/pip.git (push)</span>
<span class="go">upstream https://github.com/pypa/pip.git (fetch)</span>
<span class="go">upstream https://github.com/pypa/pip.git (push)</span>
</pre></div>
</div>
<p>In the example above, <code class="docutils literal notranslate"><span class="pre">USERNAME</span></code> is your username on GitHub.</p>
<p>First, fetch the latest changes from the main pip repository, <code class="docutils literal notranslate"><span class="pre">upstream</span></code>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">git fetch upstream</span>
</pre></div>
</div>
<p>Then, check out your local <code class="docutils literal notranslate"><span class="pre">main</span></code> branch, and rebase the changes on top of
it:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">git checkout main</span>
<span class="go">git rebase upstream/main</span>
</pre></div>
</div>
<p>At this point, you might have to <a class="reference external" href="https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line">resolve merge conflicts</a>. Once this is done,
push the updates you have just made to your local <code class="docutils literal notranslate"><span class="pre">main</span></code> branch to your
<code class="docutils literal notranslate"><span class="pre">origin</span></code> repository on GitHub:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">git checkout main</span>
<span class="go">git push origin main</span>
</pre></div>
</div>
<p>Now your local <code class="docutils literal notranslate"><span class="pre">main</span></code> branch and the <code class="docutils literal notranslate"><span class="pre">main</span></code> branch in your <code class="docutils literal notranslate"><span class="pre">origin</span></code>
repo have been updated with the most recent changes from the main pip
repository.</p>
<p>To keep your branches updated, the process is similar:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">git checkout awesome-feature</span>
<span class="go">git fetch upstream</span>
<span class="go">git rebase upstream/main</span>
</pre></div>
</div>
<p>Now your branch has been updated with the latest changes from the
<code class="docutils literal notranslate"><span class="pre">main</span></code> branch on the upstream pip repository.</p>
<p>It’s good practice to back up your branches by pushing them to your
<code class="docutils literal notranslate"><span class="pre">origin</span></code> on GitHub as you are working on them. To push a branch,
run this command:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">git push origin awesome-feature</span>
</pre></div>
</div>
<p>In this example, <code class="docutils literal notranslate"><span class="pre"><awesome-feature></span></code> is the name of your branch. This
will push the branch you are working on to GitHub, but will not
create a PR.</p>
<p>Once you have pushed your branch to your <code class="docutils literal notranslate"><span class="pre">origin</span></code>, if you need to
update it again, you will have to force push your changes by running the
following command:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">git push -f origin awesome-feature</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">-f</span></code> (or <code class="docutils literal notranslate"><span class="pre">--force</span></code>) flag after <code class="docutils literal notranslate"><span class="pre">push</span></code> forces updates from your local
branch to update your <code class="docutils literal notranslate"><span class="pre">origin</span></code> branch. If you have a PR open on your
branch, force pushing will update your PR. (This is a useful command
when someone requests changes on a PR.)</p>
<p>If you get an error message like this:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">! [rejected] awesome-feature -> awesome-feature (non-fast-forward)</span>
<span class="go">error: failed to push some refs to 'https://github.com/USERNAME/pip.git'</span>
<span class="go">hint: Updates were rejected because the tip of your current branch is behind</span>
<span class="go">hint: its remote counterpart. Integrate the remote changes (e.g.</span>
<span class="go">hint: 'git pull ...') before pushing again.</span>
<span class="go">hint: See the 'Note about fast-forwards' in 'git push --help' for details.</span>
</pre></div>
</div>
<p>Try force-pushing your branch with <code class="docutils literal notranslate"><span class="pre">push</span> <span class="pre">-f</span></code>.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">main</span></code> branch in the main pip repository gets updated frequently, so
you might have to update your branch at least once while you are working on it.</p>
<p>Thank you for your contribution!</p>
</section>
<section id="becoming-a-maintainer">
<h2>Becoming a maintainer<a class="headerlink" href="#becoming-a-maintainer" title="Link to this heading">¶</a></h2>
<p>If you want to become an official maintainer, start by helping out.</p>
<p>As a first step, we welcome you to triage issues on pip’s issue
tracker. pip maintainers provide triage abilities to contributors once
they have been around for some time (probably at least 2-3 months) and
contributed positively to the project. This is optional and highly
recommended for becoming a pip maintainer.</p>
<p>Later, when you think you’re ready (probably at least 5 months after
starting to triage), get in touch with one of the maintainers and they
will initiate a vote among the existing maintainers.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Upon becoming a maintainer, a person should be given access to various
pip-related tooling across multiple platforms. These are noted here for
future reference by the maintainers:</p>
<ul class="simple">
<li><p>GitHub Push Access</p></li>
<li><p>PyPI Publishing Access</p></li>
<li><p>CI Administration capabilities</p></li>
<li><p>ReadTheDocs Administration capabilities</p></li>
</ul>
</div>
</section>
</section>
</article>
</div>
<footer>
<div class="related-pages">
<a class="next-page" href="ci.html">
<div class="page-info">
<div class="context">
<span>Next</span>
</div>
<div class="title">Continuous Integration</div>
</div>
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
</a>
<a class="prev-page" href="getting-started.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">Getting Started</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="#">Contributing</a><ul>
<li><a class="reference internal" href="#pip-s-internals">Pip’s internals</a></li>
<li><a class="reference internal" href="#submitting-pull-requests">Submitting Pull Requests</a></li>
<li><a class="reference internal" href="#automated-testing">Automated Testing</a></li>
<li><a class="reference internal" href="#news-entries">NEWS Entries</a><ul>
<li><a class="reference internal" href="#contents-of-a-news-entry">Contents of a NEWS entry</a></li>
<li><a class="reference internal" href="#choosing-the-type-of-news-entry">Choosing the type of NEWS entry</a></li>
</ul>
</li>
<li><a class="reference internal" href="#updating-your-branch">Updating your branch</a></li>
<li><a class="reference internal" href="#becoming-a-maintainer">Becoming a maintainer</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>