CINXE.COM

<!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/" /><link rel="copyright" title="Copyright" href="../../copyright/" /><link rel="next" title="VCS Support" href="../vcs-support/" /><link rel="prev" title="Repeatable Installs" href="../repeatable-installs/" />  <title>Secure installs - pip documentation v24.3.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=354aac6f" /> <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=302659d7" /> <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><script async type="text/javascript" src="/_/static/javascript/readthedocs-addons.js"></script><meta name="readthedocs-project-slug" content="pip" /><meta name="readthedocs-version-slug" content="stable" /><meta name="readthedocs-resolver-filename" content="/topics/secure-installs/" /><meta name="readthedocs-http-status" content="200" /></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="../../"><div class="brand">pip documentation v24.3.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="../../"> <span class="sidebar-brand-text">pip documentation v24.3.1</span> </a><form class="sidebar-search-container" method="get" action="../../search/" 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/">Getting Started</a></li> <li class="toctree-l1"><a class="reference internal" href="../../installation/">Installation</a></li> <li class="toctree-l1"><a class="reference internal" href="../../user_guide/">User Guide</a></li> <li class="toctree-l1 current has-children"><a class="reference internal" href="../">Topic Guides</a><input checked="" 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 class="current"> <li class="toctree-l2"><a class="reference internal" href="../authentication/">Authentication</a></li> <li class="toctree-l2"><a class="reference internal" href="../caching/">Caching</a></li> <li class="toctree-l2"><a class="reference internal" href="../configuration/">Configuration</a></li> <li class="toctree-l2"><a class="reference internal" href="../dependency-resolution/">Dependency Resolution</a></li> <li class="toctree-l2"><a class="reference internal" href="../more-dependency-resolution/">More on Dependency Resolution</a></li> <li class="toctree-l2"><a class="reference internal" href="../https-certificates/">HTTPS Certificates</a></li> <li class="toctree-l2"><a class="reference internal" href="../local-project-installs/">Local project installs</a></li> <li class="toctree-l2"><a class="reference internal" href="../repeatable-installs/">Repeatable Installs</a></li> <li class="toctree-l2 current current-page"><a class="current reference internal" href="#">Secure installs</a></li> <li class="toctree-l2"><a class="reference internal" href="../vcs-support/">VCS Support</a></li> <li class="toctree-l2"><a class="reference internal" href="../python-option/">Managing a different Python interpreter</a></li> <li class="toctree-l2"><a class="reference internal" href="../workflow/">Pip is not a workflow management tool</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../reference/">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/">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/"><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/"><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/">Requirement Specifiers</a></li> <li class="toctree-l2"><a class="reference internal" href="../../reference/requirements-file-format/">Requirements File Format</a></li> <li class="toctree-l2"><a class="reference internal" href="../../reference/installation-report/">Installation Report</a></li> <li class="toctree-l2"><a class="reference internal" href="../../reference/inspect-report/"><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/">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/">pip</a></li> <li class="toctree-l2"><a class="reference internal" href="../../cli/pip_install/">pip install</a></li> <li class="toctree-l2"><a class="reference internal" href="../../cli/pip_uninstall/">pip uninstall</a></li> <li class="toctree-l2"><a class="reference internal" href="../../cli/pip_inspect/">pip inspect</a></li> <li class="toctree-l2"><a class="reference internal" href="../../cli/pip_list/">pip list</a></li> <li class="toctree-l2"><a class="reference internal" href="../../cli/pip_show/">pip show</a></li> <li class="toctree-l2"><a class="reference internal" href="../../cli/pip_freeze/">pip freeze</a></li> <li class="toctree-l2"><a class="reference internal" href="../../cli/pip_check/">pip check</a></li> <li class="toctree-l2"><a class="reference internal" href="../../cli/pip_download/">pip download</a></li> <li class="toctree-l2"><a class="reference internal" href="../../cli/pip_wheel/">pip wheel</a></li> <li class="toctree-l2"><a class="reference internal" href="../../cli/pip_hash/">pip hash</a></li> <li class="toctree-l2"><a class="reference internal" href="../../cli/pip_search/">pip search</a></li> <li class="toctree-l2"><a class="reference internal" href="../../cli/pip_cache/">pip cache</a></li> <li class="toctree-l2"><a class="reference internal" href="../../cli/pip_config/">pip config</a></li> <li class="toctree-l2"><a class="reference internal" href="../../cli/pip_debug/">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/">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/">Getting Started</a></li> <li class="toctree-l2"><a class="reference internal" href="../../development/contributing/">Contributing</a></li> <li class="toctree-l2"><a class="reference internal" href="../../development/ci/">Continuous Integration</a></li> <li class="toctree-l2"><a class="reference internal" href="../../development/issue-triage/">Issue Triage</a></li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../development/architecture/">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/">Broad functionality overview</a></li> <li class="toctree-l3"><a class="reference internal" href="../../development/architecture/anatomy/">Repository anatomy & directory structure</a></li> <li class="toctree-l3"><a class="reference internal" href="../../development/architecture/configuration-files/">Configuration File Handling</a></li> <li class="toctree-l3"><a class="reference internal" href="../../development/architecture/package-finding/">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/">Command Line Interface</a></li> <li class="toctree-l3"><a class="reference internal" href="../../development/architecture/upgrade-options/">Options that control the installation process</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="../../development/release-process/">Release process</a></li> <li class="toctree-l2"><a class="reference internal" href="../../development/vendoring-policy/">Vendoring Policy</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../ux-research-design/">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/">How to Contribute</a></li> <li class="toctree-l2"><a class="reference internal" href="../../ux-research-design/guidance/">UX Guidance</a></li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../ux-research-design/research-results/">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/">About pip’s Users</a></li> <li class="toctree-l3"><a class="reference internal" href="../../ux-research-design/research-results/mental-models/">How Users Understand pip</a></li> <li class="toctree-l3"><a class="reference internal" href="../../ux-research-design/research-results/users-and-security/">How pip users think about security</a></li> <li class="toctree-l3"><a class="reference internal" href="../../ux-research-design/research-results/ci-cd/">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/">pip Personas</a></li> <li class="toctree-l3"><a class="reference internal" href="../../ux-research-design/research-results/prioritizing-features/">Prioritizing pip Features</a></li> <li class="toctree-l3"><a class="reference internal" href="../../ux-research-design/research-results/override-conflicting-dependencies/">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/">pip --force-reinstall</a></li> <li class="toctree-l3"><a class="reference internal" href="../../ux-research-design/research-results/pip-search/">pip search</a></li> <li class="toctree-l3"><a class="reference internal" href="../../ux-research-design/research-results/pip-upgrade-conflict/">pip Upgrade Conflict</a></li> <li class="toctree-l3"><a class="reference internal" href="../../ux-research-design/research-results/improving-pips-documentation/">Improving pip’s Documentation</a></li> </ul> </li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="../../news/">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/topics/secure-installs.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="secure-installs"> <h1>Secure installs<a class="headerlink" href="#secure-installs" title="Link to this heading">¶</a></h1> <p>By default, pip does not perform any checks to protect against remote tampering and involves running arbitrary code from distributions. It is, however, possible to use pip in a manner that changes these behaviours, to provide a more secure installation mechanism.</p> <p>This can be achieved by doing the following:</p> <ul class="simple"> <li><p>Enable <a class="reference internal" href="#hash-checking-mode"><span class="std std-ref">Hash-checking Mode</span></a>, by passing <a class="reference internal" href="../../cli/pip_download/#cmdoption-require-hashes"><code class="xref any std std-option docutils literal notranslate"><span class="pre">--require-hashes</span></code></a></p></li> <li><p>Disallow source distributions, by passing <a class="reference internal" href="../../cli/pip_download/#cmdoption-only-binary"><code class="xref any std std-option docutils literal notranslate"><span class="pre">--only-binary</span> <span class="pre">:all:</span></code></a></p></li> </ul> <section id="hash-checking-mode"> <span id="id1"></span><h2>Hash-checking Mode<a class="headerlink" href="#hash-checking-mode" title="Link to this heading">¶</a></h2> <div class="versionadded"> <p><span class="versionmodified added">Added in version 8.0.</span></p> </div> <p>This mode uses local hashes, embedded in a requirements.txt file, to protect against remote tampering and network issues. These hashes are specified using a <code class="docutils literal notranslate"><span class="pre">--hash</span></code> <a class="reference internal" href="../../reference/requirements-file-format/#per-requirement-options"><span class="std std-ref">per requirement option</span></a>.</p> <p>Note that hash-checking is an all-or-nothing proposition. Specifying <code class="docutils literal notranslate"><span class="pre">--hash</span></code> against <em>any</em> requirement will activate this mode globally.</p> <p>To add hashes for a package, add them to line as follows:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">FooProject</span> <span class="o">==</span> <span class="mf">1.2</span> \ <span class="o">--</span><span class="nb">hash</span><span class="o">=</span><span class="n">sha256</span><span class="p">:</span><span class="mi">2</span><span class="n">cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824</span> \ <span class="o">--</span><span class="nb">hash</span><span class="o">=</span><span class="n">sha256</span><span class="p">:</span><span class="mi">486</span><span class="n">ea46224d1bb4fb680f34f7c9ad96a8f24ec88be73ea8e5a6c65260e9cb8a7</span> </pre></div> </div> <section id="additional-restrictions"> <h3>Additional restrictions<a class="headerlink" href="#additional-restrictions" title="Link to this heading">¶</a></h3> <ul> <li><p>Hashes are required for <em>all</em> requirements.</p> <p>This is because a partially-hashed requirements file is of little use and thus likely an error: a malicious actor could slip bad code into the installation via one of the unhashed requirements.</p> <p>Note that hashes embedded in URL-style requirements via the <code class="docutils literal notranslate"><span class="pre">#md5=...</span></code> syntax suffice to satisfy this rule (regardless of hash strength, for legacy reasons), though you should use a stronger hash like sha256 whenever possible.</p> </li> <li><p>Hashes are required for <em>all</em> dependencies.</p> <p>If there is a dependency that is not spelled out and hashed in the requirements file, it will result in an error.</p> </li> <li><p>Requirements must be pinned (either to a URL, filesystem path or using <code class="docutils literal notranslate"><span class="pre">==</span></code>).</p> <p>This prevents a surprising hash mismatch upon the release of a new version that matches the requirement specifier.</p> </li> </ul> </section> <section id="forcing-hash-checking-mode"> <h3>Forcing Hash-checking mode<a class="headerlink" href="#forcing-hash-checking-mode" title="Link to this heading">¶</a></h3> <p>It is possible to force the hash checking mode to be enabled, by passing <code class="docutils literal notranslate"><span class="pre">--require-hashes</span></code> command-line option.</p> <p>This can be useful in deploy scripts, to ensure that the author of the requirements file provided hashes. It is also a convenient way to bootstrap your list of hashes, since it shows the hashes of the packages it fetched. It fetches only the preferred archive for each package, so you may still need to add hashes for alternatives archives using <a class="reference internal" href="../../cli/pip_hash/#pip-hash"><span class="std std-ref">pip hash</span></a>: for instance if there is both a binary and a source distribution.</p> </section> <section id="hash-algorithms"> <h3>Hash algorithms<a class="headerlink" href="#hash-algorithms" title="Link to this heading">¶</a></h3> <p>The recommended hash algorithm at the moment is sha256, but stronger ones are allowed, including all those supported by <code class="docutils literal notranslate"><span class="pre">hashlib</span></code>. However, weaker ones such as md5, sha1, and sha224 are excluded to avoid giving a false sense of security.</p> </section> <section id="multiple-hashes-per-package"> <h3>Multiple hashes per package<a class="headerlink" href="#multiple-hashes-per-package" title="Link to this heading">¶</a></h3> <p>It is possible to use multiple hashes for each package. This is important when a package offers binary distributions for a variety of platforms or when it is important to allow both binary and source distributions.</p> </section> <section id="interaction-with-caching"> <h3>Interaction with caching<a class="headerlink" href="#interaction-with-caching" title="Link to this heading">¶</a></h3> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 23.1: </span>The <a class="reference internal" href="../caching/#wheel-caching"><span class="std std-ref">locally-built wheel cache</span></a> is used in hash-checking mode too.</p> </div> <p>When installing from the cache of locally built wheels in hash-checking mode, pip verifies the hashes against those of the original source distribution that was used to build the wheel. These original hashes are obtained from a <code class="docutils literal notranslate"><span class="pre">origin.json</span></code> file stored in each cache entry.</p> </section> <section id="using-hashes-from-pypi-or-other-index-servers"> <h3>Using hashes from PyPI (or other index servers)<a class="headerlink" href="#using-hashes-from-pypi-or-other-index-servers" title="Link to this heading">¶</a></h3> <p>PyPI (and certain other index servers) provides a hash for the distribution, in the fragment portion of each download URL, like <code class="docutils literal notranslate"><span class="pre">#sha256=123...</span></code>, which pip checks as a protection against download corruption.</p> <p>Other hash algorithms that have guaranteed support from <code class="docutils literal notranslate"><span class="pre">hashlib</span></code> are also supported here: sha1, sha224, sha384, sha256, and sha512. Since this hash originates remotely, it is not a useful guard against tampering and thus does not satisfy the <code class="docutils literal notranslate"><span class="pre">--require-hashes</span></code> demand that every package have a local hash.</p> </section> </section> <section id="repeatable-installs"> <h2>Repeatable installs<a class="headerlink" href="#repeatable-installs" title="Link to this heading">¶</a></h2> <p>Hash-checking mode also works with <a class="reference internal" href="../../cli/pip_download/#pip-download"><span class="std std-ref">pip download</span></a> and <a class="reference internal" href="../../cli/pip_wheel/#pip-wheel"><span class="std std-ref">pip wheel</span></a>. See <a class="reference internal" href="../repeatable-installs/"><span class="doc">Repeatable Installs</span></a> for a comparison of hash-checking mode with other repeatability strategies.</p> <div class="admonition warning"> <p class="admonition-title">Warning</p> <p>Beware of the <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> keyword arg in <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code>. The (rare) packages that use it will cause those dependencies to be downloaded by setuptools directly, skipping pip’s hash-checking. If you need to use such a package, see <a class="reference internal" href="../../reference/build-system/#controlling-setup-requires"><span class="std std-ref">controlling setup_requires</span></a>.</p> </div> </section> <section id="do-not-use-setuptools-directly"> <h2>Do not use setuptools directly<a class="headerlink" href="#do-not-use-setuptools-directly" title="Link to this heading">¶</a></h2> <p>Be careful not to nullify all your security work by installing your actual project by using setuptools’ deprecated interfaces directly: for example, by calling <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">install</span></code>, <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">develop</span></code>, or <code class="docutils literal notranslate"><span class="pre">easy_install</span></code>.</p> <p>These will happily go out and download, unchecked, anything you missed in your requirements file and it’s easy to miss things as your project evolves. To be safe, install your project using pip and <a class="reference internal" href="../../cli/pip_download/#cmdoption-no-deps"><code class="xref any std std-option docutils literal notranslate"><span class="pre">--no-deps</span></code></a>.</p> <p>Instead of <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">install</span></code>, use:</p> <p><div class="tab-set docutils"> <input checked="True" class="tab-input" id="tab-set--0-input--1" name="tab-set--0" type="radio"><label class="tab-label" for="tab-set--0-input--1">Linux</label><div class="tab-content docutils"> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>--no-deps<span class="w"> </span>. </pre></div> </div> </div> <input class="tab-input" id="tab-set--0-input--2" name="tab-set--0" type="radio"><label class="tab-label" for="tab-set--0-input--2">MacOS</label><div class="tab-content docutils"> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>--no-deps<span class="w"> </span>. </pre></div> </div> </div> <input class="tab-input" id="tab-set--0-input--3" name="tab-set--0" type="radio"><label class="tab-label" for="tab-set--0-input--3">Windows</label><div class="tab-content docutils"> <div class="highlight-doscon notranslate"><div class="highlight"><pre><span></span><span class="gp">C:></span> py -m pip install --no-deps . </pre></div> </div> </div> </div> </p> <p>Instead of <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">develop</span></code>, use:</p> <p><div class="tab-set docutils"> <input checked="True" class="tab-input" id="tab-set--1-input--1" name="tab-set--1" type="radio"><label class="tab-label" for="tab-set--1-input--1">Linux</label><div class="tab-content docutils"> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>--no-deps<span class="w"> </span>-e<span class="w"> </span>. </pre></div> </div> </div> <input class="tab-input" id="tab-set--1-input--2" name="tab-set--1" type="radio"><label class="tab-label" for="tab-set--1-input--2">MacOS</label><div class="tab-content docutils"> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>--no-deps<span class="w"> </span>-e<span class="w"> </span>. </pre></div> </div> </div> <input class="tab-input" id="tab-set--1-input--3" name="tab-set--1" type="radio"><label class="tab-label" for="tab-set--1-input--3">Windows</label><div class="tab-content docutils"> <div class="highlight-doscon notranslate"><div class="highlight"><pre><span></span><span class="gp">C:></span> py -m pip install --no-deps -e . </pre></div> </div> </div> </div> </p> </section> </section> </article> </div> <footer> <div class="related-pages"> <a class="next-page" href="../vcs-support/"> <div class="page-info"> <div class="context"> <span>Next</span> </div> <div class="title">VCS Support</div> </div> <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> </a> <a class="prev-page" href="../repeatable-installs/"> <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">Repeatable Installs</div> </div> </a> </div> <div class="bottom-of-page"> <div class="left-details"> <div class="copyright"> <a href="../../copyright/">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="#">Secure installs</a><ul> <li><a class="reference internal" href="#hash-checking-mode">Hash-checking Mode</a><ul> <li><a class="reference internal" href="#additional-restrictions">Additional restrictions</a></li> <li><a class="reference internal" href="#forcing-hash-checking-mode">Forcing Hash-checking mode</a></li> <li><a class="reference internal" href="#hash-algorithms">Hash algorithms</a></li> <li><a class="reference internal" href="#multiple-hashes-per-package">Multiple hashes per package</a></li> <li><a class="reference internal" href="#interaction-with-caching">Interaction with caching</a></li> <li><a class="reference internal" href="#using-hashes-from-pypi-or-other-index-servers">Using hashes from PyPI (or other index servers)</a></li> </ul> </li> <li><a class="reference internal" href="#repeatable-installs">Repeatable installs</a></li> <li><a class="reference internal" href="#do-not-use-setuptools-directly">Do not use setuptools directly</a></li> </ul> </li> </ul> </div> </div> </div> </aside> </div> </div><script src="../../_static/documentation_options.js?v=e1329b18"></script> <script src="../../_static/doctools.js?v=9a2dae69"></script> <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script> <script src="../../_static/scripts/furo.js?v=5fa4622c"></script> <script src="../../_static/clipboard.min.js?v=a7894cd8"></script> <script src="../../_static/copybutton.js?v=80126f2a"></script> <script src="../../_static/tabs.js?v=3ee01567"></script> </body> </html>