CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 439 – Inclusion of implicit pip bootstrap in Python installation | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0439/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 439 – Inclusion of implicit pip bootstrap in Python installation | peps.python.org'> <meta property="og:description" content="This PEP proposes the inclusion of a pip bootstrap executable in the Python installation to simplify the use of 3rd-party modules by Python users."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0439/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="This PEP proposes the inclusion of a pip bootstrap executable in the Python installation to simplify the use of 3rd-party modules by Python users."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</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"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</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"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <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"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</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"> <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> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 439</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> <span class="visually-hidden">Toggle light / dark / auto colour theme</span> </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 439 – Inclusion of implicit pip bootstrap in Python installation</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author<span class="colon">:</span></dt> <dd class="field-odd">Richard Jones <richard at python.org></dd> <dt class="field-even">BDFL-Delegate<span class="colon">:</span></dt> <dd class="field-even">Alyssa Coghlan <ncoghlan at gmail.com></dd> <dt class="field-odd">Discussions-To<span class="colon">:</span></dt> <dd class="field-odd"><a class="reference external" href="https://mail.python.org/archives/list/distutils-sig@python.org/">Distutils-SIG list</a></dd> <dt class="field-even">Status<span class="colon">:</span></dt> <dd class="field-even"><abbr title="Formally declined and will not be accepted">Rejected</abbr></dd> <dt class="field-odd">Type<span class="colon">:</span></dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Topic<span class="colon">:</span></dt> <dd class="field-even"><a class="reference external" href="../topic/packaging/">Packaging</a></dd> <dt class="field-odd">Created<span class="colon">:</span></dt> <dd class="field-odd">18-Mar-2013</dd> <dt class="field-even">Python-Version<span class="colon">:</span></dt> <dd class="field-even">3.4</dd> <dt class="field-odd">Post-History<span class="colon">:</span></dt> <dd class="field-odd">19-Mar-2013</dd> <dt class="field-even">Resolution<span class="colon">:</span></dt> <dd class="field-even"><a class="reference external" href="https://mail.python.org/pipermail/distutils-sig/2013-August/022527.html">Distutils-SIG message</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#pep-rejection">PEP Rejection</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#proposal">Proposal</a><ul> <li><a class="reference internal" href="#the-pip-bootstrap">The pip bootstrap</a></li> <li><a class="reference internal" href="#modifications-to-publishing-packages">Modifications to publishing packages</a></li> </ul> </li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#risks">Risks</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#acknowledgments">Acknowledgments</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> <p>This PEP proposes the inclusion of a pip bootstrap executable in the Python installation to simplify the use of 3rd-party modules by Python users.</p> <p>This PEP does not propose to include the pip implementation in the Python standard library. Nor does it propose to implement any package management or installation mechanisms beyond those provided by PEP 427 (“The Wheel Binary Package Format 1.0”) and TODO distlib PEP.</p> </section> <section id="pep-rejection"> <h2><a class="toc-backref" href="#pep-rejection" role="doc-backlink">PEP Rejection</a></h2> <p>This PEP has been rejected in favour of a more explicit mechanism that should achieve the same end result in a more reliable fashion. The more explicit bootstrapping mechanism is described in <a class="pep reference internal" href="../pep-0453/" title="PEP 453 – Explicit bootstrapping of pip in Python installations">PEP 453</a>.</p> </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> <p>Currently the user story for installing 3rd-party Python modules is not as simple as it could be. It requires that all 3rd-party modules inform the user of how to install the installer, typically via a link to the installer. That link may be out of date or the steps required to perform the install of the installer may be enough of a roadblock to prevent the user from further progress.</p> <p>Large Python projects which emphasise a low barrier to entry have shied away from depending on third party packages because of the introduction of this potential stumbling block for new users.</p> <p>With the inclusion of the package installer command in the standard Python installation the barrier to installing additional software is considerably reduced. It is hoped that this will therefore increase the likelihood that Python projects will reuse third party software.</p> <p>The Python community also has an issue of complexity around the current bootstrap procedure for pip and setuptools. They all have their own bootstrap download file with slightly different usages and even refer to each other in some cases. Having a single bootstrap which is common amongst them all, with a simple usage, would be far preferable.</p> <p>It is also hoped that this is reduces the number of proposals to include more and more software in the Python standard library, and therefore that more popular Python software is more easily upgradeable beyond requiring Python installation upgrades.</p> </section> <section id="proposal"> <h2><a class="toc-backref" href="#proposal" role="doc-backlink">Proposal</a></h2> <p>The bootstrap will install the pip implementation, setuptools by downloading their installation files from PyPI.</p> <p>This proposal affects two components of packaging: <a class="reference internal" href="#the-pip-bootstrap">the pip bootstrap</a> and, thanks to easier package installation, <a class="reference internal" href="#modifications-to-publishing-packages">modifications to publishing packages</a>.</p> <p>The core of this proposal is that the user experience of using pip should not require the user to install pip.</p> <section id="the-pip-bootstrap"> <h3><a class="toc-backref" href="#the-pip-bootstrap" role="doc-backlink">The pip bootstrap</a></h3> <p>The Python installation includes an executable called “pip3” (see <a class="pep reference internal" href="../pep-0394/" title="PEP 394 – The “python” Command on Unix-Like Systems">PEP 394</a> for naming rationale etc.) that attempts to import pip machinery. If it can then the pip command proceeds as normal. If it cannot it will bootstrap pip by downloading the pip implementation and setuptools wheel files. Hereafter the installation of the “pip implementation” will imply installation of setuptools and virtualenv. Once installed, the pip command proceeds as normal. Once the bootstrap process is complete the “pip3” command is no longer the bootstrap but rather the full pip command.</p> <p>A bootstrap is used in the place of a the full pip code so that we don’t have to bundle pip and also pip is upgradeable outside of the regular Python upgrade timeframe and processes.</p> <p>To avoid issues with sudo we will have the bootstrap default to installing the pip implementation to the per-user site-packages directory defined in <a class="pep reference internal" href="../pep-0370/" title="PEP 370 – Per user site-packages directory">PEP 370</a> and implemented in Python 2.6/3.0. Since we avoid installing to the system Python we also avoid conflicting with any other packaging system (on Linux systems, for example.) If the user is inside a <a class="pep reference internal" href="../pep-0405/" title="PEP 405 – Python Virtual Environments">PEP 405</a> virtual environment then the pip implementation will be installed into that virtual environment.</p> <p>The bootstrap process will proceed as follows:</p> <ol class="arabic simple"> <li>The user system has Python (3.4+) installed. In the “scripts” directory of the Python installation there is the bootstrap script called “pip3”.</li> <li>The user will invoke a pip command, typically “pip3 install <package>”, for example “pip3 install Django”.</li> <li>The bootstrap script will attempt to import the pip implementation. If this succeeds, the pip command is processed normally. Stop.</li> <li>On failing to import the pip implementation the bootstrap notifies the user that it needs to “install pip”. It will ask the user whether it should install pip as a system-wide site-packages or as a user-only package. This choice will also be present as a command-line option to pip so non-interactive use is possible.</li> <li>The bootstrap will and contact PyPI to obtain the latest download wheel file (see <a class="pep reference internal" href="../pep-0427/" title="PEP 427 – The Wheel Binary Package Format 1.0">PEP 427</a>.)</li> <li>Upon downloading the file it is installed using “python setup.py install”.</li> <li>The pip tool may now import the pip implementation and continues to process the requested user command normally.</li> </ol> <p>Users may be running in an environment which cannot access the public Internet and are relying solely on a local package repository. They would use the “-i” (Base URL of Python Package Index) argument to the “pip3 install” command. This simply overrides the default index URL pointing to PyPI.</p> <p>Some users may have no Internet access suitable for fetching the pip implementation file. These users can manually download and install the setuptools and pip tar files. Adding specific support for this use-case is unnecessary.</p> <p>The download of the pip implementation install file will be performed securely. The transport from pypi.python.org will be done over HTTPS with the CA certificate check performed. This facility will be present in Python 3.4+ using Operating System certificates (see PEP XXXX).</p> <p>Beyond those arguments controlling index location and download options, the “pip3” bootstrap command may support further standard pip options for verbosity, quietness and logging.</p> <p>The “pip3” command will support two new command-line options that are used in the bootstrapping, and otherwise ignored. They control where the pip implementation is installed:</p> <dl class="simple"> <dt><code class="docutils literal notranslate"><span class="pre">--bootstrap</span></code></dt><dd>Install to the user’s packages directory. The name of this option is chosen to promote it as the preferred installation option.</dd> <dt><code class="docutils literal notranslate"><span class="pre">--bootstrap-to-system</span></code></dt><dd>Install to the system site-packages directory.</dd> </dl> <p>These command-line options will also need to be implemented, but otherwise ignored, in the pip implementation.</p> <p>Consideration should be given to defaulting pip to install packages to the user’s packages directory if pip is installed in that location.</p> <p>The “–no-install” option to the “pip3” command will not affect the bootstrapping process.</p> </section> <section id="modifications-to-publishing-packages"> <h3><a class="toc-backref" href="#modifications-to-publishing-packages" role="doc-backlink">Modifications to publishing packages</a></h3> <p>An additional new Python package is proposed, “pypublish”, which will be a tool for publishing packages to PyPI. It would replace the current “python setup.py register” and “python setup.py upload” distutils commands. Again because of the measured Python release cycle and extensive existing Python installations these commands are difficult to bugfix and extend. Additionally it is desired that the “register” and “upload” commands be able to be performed over HTTPS with certificate validation. Since shipping CA certificate keychains with Python is not really feasible (updating the keychain is quite difficult to manage) it is desirable that those commands, and the accompanying keychain, be made installable and upgradeable outside of Python itself.</p> <p>The existing distutils mechanisms for package registration and upload would remain, though with a deprecation warning.</p> </section> </section> <section id="implementation"> <h2><a class="toc-backref" href="#implementation" role="doc-backlink">Implementation</a></h2> <p>The changes to pip required by this PEP are being tracked in that project’s issue tracker <a class="footnote-reference brackets" href="#id3" id="id1">[2]</a>. Most notably, the addition of –bootstrap and –bootstrap-to-system to the pip command-line.</p> <p>It would be preferable that the pip and setuptools projects distribute a wheel format download.</p> <p>The required code for this implementation is the “pip3” command described above. The additional pypublish can be developed outside of the scope of this PEP’s work.</p> <p>Finally, it would be desirable that “pip3” be ported to Python 2.6+ to allow the single command to replace existing pip, setuptools and virtualenv (which would be added to the bootstrap) bootstrap scripts. Having that bootstrap included in a future Python 2.7 release would also be highly desirable.</p> </section> <section id="risks"> <h2><a class="toc-backref" href="#risks" role="doc-backlink">Risks</a></h2> <p>The key that is used to sign the pip implementation download might be compromised and this PEP currently proposes no mechanism for key revocation.</p> <p>There is a Perl package installer also named “pip”. It is quite rare and not commonly used. The Fedora variant of Linux has historically named Python’s “pip” as “python-pip” and Perl’s “pip” as “perl-pip”. This policy has been altered<a class="footnote-reference brackets" href="#id4" id="id2">[3]</a> so that future and upgraded Fedora installations will use the name “pip” for Python’s “pip”. Existing (non-upgraded) installations will still have the old name for the Python “pip”, though the potential for confusion is now much reduced.</p> </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id3" role="doc-footnote"> <dt class="label" id="id3">[<a href="#id1">2</a>]</dt> <dd>pip issue tracking work needed for this PEP <a class="reference external" href="https://github.com/pypa/pip/issues/863">https://github.com/pypa/pip/issues/863</a></aside> <aside class="footnote brackets" id="id4" role="doc-footnote"> <dt class="label" id="id4">[<a href="#id2">3</a>]</dt> <dd>Fedora’s python-pip package does not provide /usr/bin/pip <a class="reference external" href="https://bugzilla.redhat.com/show_bug.cgi?id=958377">https://bugzilla.redhat.com/show_bug.cgi?id=958377</a></aside> </aside> </section> <section id="acknowledgments"> <h2><a class="toc-backref" href="#acknowledgments" role="doc-backlink">Acknowledgments</a></h2> <p>Alyssa Coghlan for her thoughts on the proposal and dealing with the Red Hat issue.</p> <p>Jannis Leidel and Carl Meyer for their thoughts. Marcus Smith for feedback.</p> <p>Marcela Mašláňová for resolving the Fedora issue.</p> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> <p>This document has been placed in the public domain.</p> </section> </section> <hr class="docutils" /> <p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0439.rst">https://github.com/python/peps/blob/main/peps/pep-0439.rst</a></p> <p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0439.rst">2023-10-11 12:05:51 GMT</a></p> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#pep-rejection">PEP Rejection</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#proposal">Proposal</a><ul> <li><a class="reference internal" href="#the-pip-bootstrap">The pip bootstrap</a></li> <li><a class="reference internal" href="#modifications-to-publishing-packages">Modifications to publishing packages</a></li> </ul> </li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#risks">Risks</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#acknowledgments">Acknowledgments</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <br> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0439.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>