← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

Viewing changes to python-3.5.1-docs-html/_sources/library/ensurepip.txt

  • Committer: Dave Kuhlman
  • Date: 2017-04-15 16:24:56 UTC
  • Revision ID: dkuhlman@davekuhlman.org-20170415162456-iav9vozzg4iwqwv3
Updated docs

Show diffs side-by-side

added added

removed removed

Lines of Context:
python-3.5.1-docs-html/_sources/library/ensurepip.txt
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
 
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
21
 
``pip``.
22
 
 
23
 
.. note::
24
 
 
25
 
   This module *does not* access the internet. All of the components
26
 
   needed to bootstrap ``pip`` are included as internal parts of the
27
 
   package.
28
 
 
29
 
.. seealso::
30
 
 
31
 
   :ref:`installing-index`
32
 
      The end user guide for installing Python packages
33
 
 
34
 
   :pep:`453`: Explicit bootstrapping of pip in Python installations
35
 
      The original rationale and specification for this module.
36
 
 
37
 
 
38
 
Command line interface
39
 
----------------------
40
 
 
41
 
The command line interface is invoked using the interpreter's ``-m`` switch.
42
 
 
43
 
The simplest possible invocation is::
44
 
 
45
 
    python -m ensurepip
46
 
 
47
 
This invocation will install ``pip`` if it is not already installed,
48
 
but otherwise does nothing. To ensure the installed version of ``pip``
49
 
is at least as recent as the one bundled with ``ensurepip``, pass the
50
 
``--upgrade`` option::
51
 
 
52
 
    python -m ensurepip --upgrade
53
 
 
54
 
By default, ``pip`` is installed into the current virtual environment
55
 
(if one is active) or into the system site packages (if there is no
56
 
active virtual environment). The installation location can be controlled
57
 
through two additional command line options:
58
 
 
59
 
* ``--root <dir>``: Installs ``pip`` relative to the given root directory
60
 
  rather than the root of the currently active virtual environment (if any)
61
 
  or the default root for the current Python installation.
62
 
* ``--user``: Installs ``pip`` into the user site packages directory rather
63
 
  than globally for the current Python installation (this option is not
64
 
  permitted inside an active virtual environment).
65
 
 
66
 
By default, the scripts ``pipX`` and ``pipX.Y`` will be installed (where
67
 
X.Y stands for the version of Python used to invoke ``ensurepip``). The
68
 
scripts installed can be controlled through two additional command line
69
 
options:
70
 
 
71
 
* ``--altinstall``: if an alternate installation is requested, the ``pipX``
72
 
  script will *not* be installed.
73
 
 
74
 
* ``--default-pip``: if a "default pip" installation is requested, the
75
 
   ``pip`` script will be installed in addition to the two regular scripts.
76
 
 
77
 
Providing both of the script selection options will trigger an exception.
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=False, \
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 ``pipX`` and ``pipX.Y`` will be installed (where
107
 
   X.Y stands for the current version of Python).
108
 
 
109
 
   If *altinstall* is set, then ``pipX`` will *not* be installed.
110
 
 
111
 
   If *default_pip* is set, then ``pip`` will be installed in addition to
112
 
   the two regular scripts.
113
 
 
114
 
   Setting both *altinstall* and *default_pip* will trigger
115
 
   :exc:`ValueError`.
116
 
 
117
 
   *verbosity* controls the level of output to :data:`sys.stdout` from the
118
 
   bootstrapping operation.
119
 
 
120
 
   .. note::
121
 
 
122
 
      The bootstrapping process has side effects on both ``sys.path`` and
123
 
      ``os.environ``. Invoking the command line interface in a subprocess
124
 
      instead allows these side effects to be avoided.
125
 
 
126
 
   .. note::
127
 
 
128
 
      The bootstrapping process may install additional modules required by
129
 
      ``pip``, but other software should not assume those dependencies will
130
 
      always be present by default (as the dependencies may be removed in a
131
 
      future version of ``pip``).