<!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="Installation Report" href="installation-report.html" /><link rel="prev" title="Requirement Specifiers" href="requirement-specifiers.html" />
<!-- Generated with Sphinx 8.1.3 and Furo 2024.08.06 -->
<title>Requirements File Format - 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 class="current">
<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 current has-children"><a class="reference internal" href="index.html">Reference</a><input checked="" 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 class="current">
<li class="toctree-l2 has-children"><a class="reference internal" href="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="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="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="requirement-specifiers.html">Requirement Specifiers</a></li>
<li class="toctree-l2 current current-page"><a class="current reference internal" href="#">Requirements File Format</a></li>
<li class="toctree-l2"><a class="reference internal" href="installation-report.html">Installation Report</a></li>
<li class="toctree-l2"><a class="reference internal" href="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>
<li class="toctree-l1 has-children"><a class="reference internal" href="../development/index.html">Development</a><input 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>
<li class="toctree-l2"><a class="reference internal" href="../development/getting-started.html">Getting Started</a></li>
<li class="toctree-l2"><a class="reference internal" href="../development/contributing.html">Contributing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../development/ci.html">Continuous Integration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../development/issue-triage.html">Issue Triage</a></li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../development/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="../development/architecture/overview.html">Broad functionality overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="../development/architecture/anatomy.html">Repository anatomy & directory structure</a></li>
<li class="toctree-l3"><a class="reference internal" href="../development/architecture/configuration-files.html">Configuration File Handling</a></li>
<li class="toctree-l3"><a class="reference internal" href="../development/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="../development/architecture/command-line-interface.html">Command Line Interface</a></li>
<li class="toctree-l3"><a class="reference internal" href="../development/architecture/upgrade-options.html">Options that control the installation process</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../development/release-process.html">Release process</a></li>
<li class="toctree-l2"><a class="reference internal" href="../development/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/reference/requirements-file-format.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">
<section id="requirements-file-format">
<span id="id1"></span><h1>Requirements File Format<a class="headerlink" href="#requirements-file-format" title="Link to this heading">¶</a></h1>
<p>Requirements files serve as a list of items to be installed by pip, when
using <a class="reference internal" href="../cli/pip_install.html#pip-install"><span class="std std-ref">pip install</span></a>. Files that use this format are often called
“pip requirements.txt files”, since <code class="docutils literal notranslate"><span class="pre">requirements.txt</span></code> is usually what
these files are named (although, that is not a requirement).</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The requirements file format is closely tied to a number of internal details of
pip (e.g., pip’s command line options). The basic format is relatively stable
and portable but the full syntax, as described here, is only intended for
consumption by pip, and other tools should take that into account before using
it for their own purposes.</p>
</div>
<section id="example">
<h2>Example<a class="headerlink" href="#example" title="Link to this heading">¶</a></h2>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This is a comment, to show how #-prefixed lines are ignored.</span>
<span class="c1"># It is possible to specify requirements as plain names.</span>
<span class="n">pytest</span>
<span class="n">pytest</span><span class="o">-</span><span class="n">cov</span>
<span class="n">beautifulsoup4</span>
<span class="c1"># The syntax supported here is the same as that of requirement specifiers.</span>
<span class="n">docopt</span> <span class="o">==</span> <span class="mf">0.6.1</span>
<span class="n">requests</span> <span class="p">[</span><span class="n">security</span><span class="p">]</span> <span class="o">>=</span> <span class="mf">2.8.1</span><span class="p">,</span> <span class="o">==</span> <span class="mf">2.8</span><span class="o">.*</span> <span class="p">;</span> <span class="n">python_version</span> <span class="o"><</span> <span class="s2">"2.7"</span>
<span class="n">urllib3</span> <span class="o">@</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">urllib3</span><span class="o">/</span><span class="n">urllib3</span><span class="o">/</span><span class="n">archive</span><span class="o">/</span><span class="n">refs</span><span class="o">/</span><span class="n">tags</span><span class="o">/</span><span class="mf">1.26.8</span><span class="o">.</span><span class="n">zip</span>
<span class="c1"># It is possible to refer to other requirement files or constraints files.</span>
<span class="o">-</span><span class="n">r</span> <span class="n">other</span><span class="o">-</span><span class="n">requirements</span><span class="o">.</span><span class="n">txt</span>
<span class="o">-</span><span class="n">c</span> <span class="n">constraints</span><span class="o">.</span><span class="n">txt</span>
<span class="c1"># It is possible to refer to specific local distribution paths.</span>
<span class="o">./</span><span class="n">downloads</span><span class="o">/</span><span class="n">numpy</span><span class="o">-</span><span class="mf">1.9.2</span><span class="o">-</span><span class="n">cp34</span><span class="o">-</span><span class="n">none</span><span class="o">-</span><span class="n">win32</span><span class="o">.</span><span class="n">whl</span>
<span class="c1"># It is possible to refer to URLs.</span>
<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">wxpython</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">Phoenix</span><span class="o">/</span><span class="n">snapshot</span><span class="o">-</span><span class="n">builds</span><span class="o">/</span><span class="n">wxPython_Phoenix</span><span class="o">-</span><span class="mf">3.0.3</span><span class="o">.</span><span class="n">dev1820</span><span class="o">+</span><span class="mi">49</span><span class="n">a8884</span><span class="o">-</span><span class="n">cp34</span><span class="o">-</span><span class="n">none</span><span class="o">-</span><span class="n">win_amd64</span><span class="o">.</span><span class="n">whl</span>
</pre></div>
</div>
</section>
<section id="structure">
<h2>Structure<a class="headerlink" href="#structure" title="Link to this heading">¶</a></h2>
<p>Each line of the requirements file indicates something to be installed,
or arguments to <a class="reference internal" href="../cli/pip_install.html#pip-install"><span class="std std-ref">pip install</span></a>. The following forms are supported:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">[[--option]...]</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre"><requirement</span> <span class="pre">specifier></span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre"><archive</span> <span class="pre">url/path></span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[-e]</span> <span class="pre"><local</span> <span class="pre">project</span> <span class="pre">path></span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[-e]</span> <span class="pre"><vcs</span> <span class="pre">project</span> <span class="pre">url></span></code></p></li>
</ul>
<p>For details on requirement specifiers, see <a class="reference internal" href="requirement-specifiers.html#requirement-specifiers"><span class="std std-ref">Requirement Specifiers</span></a>. For
examples of all these forms, see <a class="reference internal" href="../cli/pip_install.html#pip-install-examples"><span class="std std-ref">Examples</span></a>.</p>
<section id="encoding">
<h3>Encoding<a class="headerlink" href="#encoding" title="Link to this heading">¶</a></h3>
<p>The default encoding for requirement files is <code class="docutils literal notranslate"><span class="pre">UTF-8</span></code> unless a different
encoding is specified using a <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0263/"><strong>PEP 263</strong></a> style comment (e.g. <code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">-*-</span> <span class="pre">coding:</span> <span class="pre"><encoding</span> <span class="pre">name></span> <span class="pre">-*-</span></code>).</p>
</section>
<section id="line-continuations">
<h3>Line continuations<a class="headerlink" href="#line-continuations" title="Link to this heading">¶</a></h3>
<p>A line ending in an unescaped <code class="docutils literal notranslate"><span class="pre">\</span></code> is treated as a line continuation
and the newline following it is effectively ignored.</p>
</section>
<section id="comments">
<h3>Comments<a class="headerlink" href="#comments" title="Link to this heading">¶</a></h3>
<p>A line that begins with <code class="docutils literal notranslate"><span class="pre">#</span></code> is treated as a comment and ignored. Whitespace
followed by a <code class="docutils literal notranslate"><span class="pre">#</span></code> causes the <code class="docutils literal notranslate"><span class="pre">#</span></code> and the remainder of the line to be
treated as a comment.</p>
<p>Comments are stripped <em>after</em> line continuations are processed.</p>
</section>
</section>
<section id="supported-options">
<h2>Supported options<a class="headerlink" href="#supported-options" title="Link to this heading">¶</a></h2>
<p>Requirements files only supports certain pip install options, which are listed
below.</p>
<section id="global-options">
<h3>Global options<a class="headerlink" href="#global-options" title="Link to this heading">¶</a></h3>
<p>The following options have an effect on the <em>entire</em> <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span></code> run, and
must be specified on their individual lines.</p>
<p><ul class="simple">
<li><p><a class="reference internal" href="../cli/pip_install.html#install-index-url"><span class="std std-ref">-i, --index-url</span></a></p></li>
<li><p><a class="reference internal" href="../cli/pip_install.html#install-extra-index-url"><span class="std std-ref">--extra-index-url</span></a></p></li>
<li><p><a class="reference internal" href="../cli/pip_install.html#install-no-index"><span class="std std-ref">--no-index</span></a></p></li>
<li><p><a class="reference internal" href="../cli/pip_install.html#install-constraint"><span class="std std-ref">-c, --constraint</span></a></p></li>
<li><p><a class="reference internal" href="../cli/pip_install.html#install-requirement"><span class="std std-ref">-r, --requirement</span></a></p></li>
<li><p><a class="reference internal" href="../cli/pip_install.html#install-editable"><span class="std std-ref">-e, --editable</span></a></p></li>
<li><p><a class="reference internal" href="../cli/pip_install.html#install-find-links"><span class="std std-ref">-f, --find-links</span></a></p></li>
<li><p><a class="reference internal" href="../cli/pip_install.html#install-no-binary"><span class="std std-ref">--no-binary</span></a></p></li>
<li><p><a class="reference internal" href="../cli/pip_install.html#install-only-binary"><span class="std std-ref">--only-binary</span></a></p></li>
<li><p><a class="reference internal" href="../cli/pip_install.html#install-prefer-binary"><span class="std std-ref">--prefer-binary</span></a></p></li>
<li><p><a class="reference internal" href="../cli/pip_install.html#install-require-hashes"><span class="std std-ref">--require-hashes</span></a></p></li>
<li><p><a class="reference internal" href="../cli/pip_install.html#install-pre"><span class="std std-ref">--pre</span></a></p></li>
<li><p><a class="reference internal" href="../cli/pip.html#trusted-host"><span class="std std-ref">--trusted-host</span></a></p></li>
<li><p><a class="reference internal" href="../cli/pip.html#use-feature"><span class="std std-ref">--use-feature</span></a></p></li>
</ul>
</p>
<div class="admonition-example admonition">
<p class="admonition-title">Example</p>
<p>To specify <a class="reference internal" href="../cli/pip_install.html#install-pre"><span class="std std-ref">--pre</span></a>, <a class="reference internal" href="../cli/pip_install.html#install-no-index"><span class="std std-ref">--no-index</span></a>
and two <a class="reference internal" href="../cli/pip_install.html#install-find-links"><span class="std std-ref">--find-links</span></a> locations:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">pre</span>
<span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">index</span>
<span class="o">--</span><span class="n">find</span><span class="o">-</span><span class="n">links</span> <span class="o">/</span><span class="n">my</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="n">archives</span>
<span class="o">--</span><span class="n">find</span><span class="o">-</span><span class="n">links</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">some</span><span class="o">.</span><span class="n">archives</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">archives</span>
</pre></div>
</div>
</div>
</section>
<section id="per-requirement-options">
<span id="id2"></span><h3>Per-requirement options<a class="headerlink" href="#per-requirement-options" title="Link to this heading">¶</a></h3>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 7.0.</span></p>
</div>
<p>The options which can be applied to individual requirements are:</p>
<ul class="simple">
<li><p><a class="reference internal" href="../cli/pip_install.html#install-global-option"><span class="std std-ref">--global-option</span></a></p></li>
<li><p><a class="reference internal" href="../cli/pip_install.html#install-config-settings"><span class="std std-ref">--config-settings</span></a></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--hash</span></code> (for <a class="reference internal" href="../topics/secure-installs.html#hash-checking-mode"><span class="std std-ref">Hash-checking Mode</span></a>)</p></li>
</ul>
</section>
</section>
<section id="referring-to-other-requirements-files">
<h2>Referring to other requirements files<a class="headerlink" href="#referring-to-other-requirements-files" title="Link to this heading">¶</a></h2>
<p>If you wish, you can refer to other requirements files, like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">r</span> <span class="n">more_requirements</span><span class="o">.</span><span class="n">txt</span>
</pre></div>
</div>
<p>You can also refer to <a class="reference internal" href="../user_guide.html#constraints-files"><span class="std std-ref">constraints files</span></a>, like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">c</span> <span class="n">some_constraints</span><span class="o">.</span><span class="n">txt</span>
</pre></div>
</div>
</section>
<section id="using-environment-variables">
<h2>Using environment variables<a class="headerlink" href="#using-environment-variables" title="Link to this heading">¶</a></h2>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 10.0.</span></p>
</div>
<p>pip supports the use of environment variables inside the
requirements file.</p>
<p>You have to use the POSIX format for variable names including brackets around
the uppercase name as shown in this example: <code class="docutils literal notranslate"><span class="pre">${API_TOKEN}</span></code>. pip will attempt
to find the corresponding environment variable defined on the host system at
runtime.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>There is no support for other variable expansion syntaxes such as <code class="docutils literal notranslate"><span class="pre">$VARIABLE</span></code>
and <code class="docutils literal notranslate"><span class="pre">%VARIABLE%</span></code>.</p>
</div>
<p>You can now store sensitive data (tokens, keys, etc.) in environment variables
and only specify the variable name for your requirements, letting pip lookup
the value at runtime. This approach aligns with the commonly used
<a class="reference external" href="https://12factor.net/config">12-factor configuration pattern</a>.</p>
</section>
<section id="influencing-the-build-system">
<h2>Influencing the build system<a class="headerlink" href="#influencing-the-build-system" title="Link to this heading">¶</a></h2>
<div class="admonition danger">
<p class="admonition-title">Danger</p>
<p>This disables the use of wheels (cached or otherwise). This could mean that builds will be slower, less deterministic, less reliable and may not behave correctly upon installation.</p>
<p>This mechanism is only preserved for backwards compatibility and should be considered deprecated. A future release of pip may drop these options.</p>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">--global-option</span></code> option is used to pass options to <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>.</p>
<div class="admonition attention">
<p class="admonition-title">Attention</p>
<p>These options are highly coupled with how pip invokes setuptools using the <a class="reference internal" href="build-system/setup-py.html"><span class="doc">setup.py (legacy)</span></a> build system interface. It is not compatible with newer <a class="reference internal" href="build-system/pyproject-toml.html"><span class="doc">pyproject.toml</span></a> build system interface.</p>
<p>This is will not work with other build-backends or newer setup.cfg-only projects.</p>
</div>
<p>If you have a declaration like:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>FooProject >= 1.2 --global-option="--no-user-cfg"
</pre></div>
</div>
<p>The above translates roughly into running FooProject’s <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> script as:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>python setup.py --no-user-cfg install
</pre></div>
</div>
<p>Note that the only way of giving more than one option to <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> is through multiple <code class="docutils literal notranslate"><span class="pre">--global-option</span></code> options.</p>
</section>
</section>
</article>
</div>
<footer>
<div class="related-pages">
<a class="next-page" href="installation-report.html">
<div class="page-info">
<div class="context">
<span>Next</span>
</div>
<div class="title">Installation Report</div>
</div>
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
</a>
<a class="prev-page" href="requirement-specifiers.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">Requirement Specifiers</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="#">Requirements File Format</a><ul>
<li><a class="reference internal" href="#example">Example</a></li>
<li><a class="reference internal" href="#structure">Structure</a><ul>
<li><a class="reference internal" href="#encoding">Encoding</a></li>
<li><a class="reference internal" href="#line-continuations">Line continuations</a></li>
<li><a class="reference internal" href="#comments">Comments</a></li>
</ul>
</li>
<li><a class="reference internal" href="#supported-options">Supported options</a><ul>
<li><a class="reference internal" href="#global-options">Global options</a></li>
<li><a class="reference internal" href="#per-requirement-options">Per-requirement options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#referring-to-other-requirements-files">Referring to other requirements files</a></li>
<li><a class="reference internal" href="#using-environment-variables">Using environment variables</a></li>
<li><a class="reference internal" href="#influencing-the-build-system">Influencing the build system</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>