1 :mod:`ensurepip` --- Bootstrapping the ``pip`` installer 2 ======================================================== 3 4 .. module:: ensurepip 5 :synopsis: Bootstrapping the ``pip`` installer into an existing Python 6 installation or virtual environment. 7 8 .. versionadded:: 2.7.9 9 10 The :mod:`ensurepip` package provides support for bootstrapping the ``pip`` 11 installer into an existing Python installation or virtual environment. This 12 bootstrapping approach reflects the fact that ``pip`` is an independent 13 project with its own release cycle, and the latest available stable version 14 is bundled with maintenance and feature releases of the CPython reference 15 interpreter. 16 17 In most cases, end users of Python shouldn't need to invoke this module 18 directly (as ``pip`` should be bootstrapped by default), but it may be 19 needed if installing ``pip`` was skipped when installing Python (or 20 when creating a virtual environment) or after explicitly uninstalling ``pip``. 21 22 .. note:: 23 24 This module *does not* access the internet. All of the components 25 needed to bootstrap ``pip`` are included as internal parts of the 26 package. 27 28 .. seealso:: 29 30 :ref:`installing-index` 31 The end user guide for installing Python packages 32 33 :pep:`453`: Explicit bootstrapping of pip in Python installations 34 The original rationale and specification for this module. 35 36 :pep:`477`: Backport ensurepip (PEP 453) to Python 2.7 37 The rationale and specification for backporting PEP 453 to Python 2.7. 38 39 40 Command line interface 41 ---------------------- 42 43 The command line interface is invoked using the interpreter's ``-m`` switch. 44 45 The simplest possible invocation is:: 46 47 python -m ensurepip 48 49 This invocation will install ``pip`` if it is not already installed, 50 but otherwise does nothing. To ensure the installed version of ``pip`` 51 is at least as recent as the one bundled with ``ensurepip``, pass the 52 ``--upgrade`` option:: 53 54 python -m ensurepip --upgrade 55 56 By default, ``pip`` is installed into the current virtual environment 57 (if one is active) or into the system site packages (if there is no 58 active virtual environment). The installation location can be controlled 59 through two additional command line options: 60 61 * ``--root <dir>``: Installs ``pip`` relative to the given root directory 62 rather than the root of the currently active virtual environment (if any) 63 or the default root for the current Python installation. 64 * ``--user``: Installs ``pip`` into the user site packages directory rather 65 than globally for the current Python installation (this option is not 66 permitted inside an active virtual environment). 67 68 By default, the scripts ``pip``, ``pipX``, and ``pipX.Y`` will be installed 69 (where X.Y stands for the version of Python used to invoke ``ensurepip``). The 70 scripts installed can be controlled through two additional command line 71 options: 72 73 * ``--altinstall``: if an alternate installation is requested, the ``pip`` and 74 ``pipX`` script will *not* be installed. 75 76 * ``--no-default-pip``: if a non-default installation is request, the ``pip`` 77 script will *not* be installed. 78 79 80 Module API 81 ---------- 82 83 :mod:`ensurepip` exposes two functions for programmatic use: 84 85 .. function:: version() 86 87 Returns a string specifying the bundled version of pip that will be 88 installed when bootstrapping an environment. 89 90 .. function:: bootstrap(root=None, upgrade=False, user=False, \ 91 altinstall=False, default_pip=True, \ 92 verbosity=0) 93 94 Bootstraps ``pip`` into the current or designated environment. 95 96 *root* specifies an alternative root directory to install relative to. 97 If *root* is ``None``, then installation uses the default install location 98 for the current environment. 99 100 *upgrade* indicates whether or not to upgrade an existing installation 101 of an earlier version of ``pip`` to the bundled version. 102 103 *user* indicates whether to use the user scheme rather than installing 104 globally. 105 106 By default, the scripts ``pip``, ``pipX``, and ``pipX.Y`` will be installed 107 (where X.Y stands for the current version of Python). 108 109 If *altinstall* is set, then ``pip`` and ``pipX`` will *not* be installed. 110 111 If *default_pip* is set to ``False``, then ``pip`` will *not* be installed. 112 113 Setting both *altinstall* and *default_pip* will trigger 114 :exc:`ValueError`. 115 116 *verbosity* controls the level of output to :data:`sys.stdout` from the 117 bootstrapping operation. 118 119 .. note:: 120 121 The bootstrapping process has side effects on both ``sys.path`` and 122 ``os.environ``. Invoking the command line interface in a subprocess 123 instead allows these side effects to be avoided. 124 125 .. note:: 126 127 The bootstrapping process may install additional modules required by 128 ``pip``, but other software should not assume those dependencies will 129 always be present by default (as the dependencies may be removed in a 130 future version of ``pip``). 131
