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