← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

Viewing changes to python-2.7.11-docs-html/_sources/installing/index.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-2.7.11-docs-html/_sources/installing/index.txt
1
 
.. highlightlang:: none
2
 
 
3
 
.. _installing-index:
4
 
 
5
 
*****************************
6
 
  Installing Python Modules
7
 
*****************************
8
 
 
9
 
:Email: distutils-sig@python.org
10
 
 
11
 
As a popular open source development project, Python has an active
12
 
supporting community of contributors and users that also make their software
13
 
available for other Python developers to use under open source license terms.
14
 
 
15
 
This allows Python users to share and collaborate effectively, benefiting
16
 
from the solutions others have already created to common (and sometimes
17
 
even rare!) problems, as well as potentially contributing their own
18
 
solutions to the common pool.
19
 
 
20
 
This guide covers the installation part of the process. For a guide to
21
 
creating and sharing your own Python projects, refer to the
22
 
:ref:`distribution guide <distributing-index>`.
23
 
 
24
 
.. note::
25
 
 
26
 
   For corporate and other institutional users, be aware that many
27
 
   organisations have their own policies around using and contributing to
28
 
   open source software. Please take such policies into account when making
29
 
   use of the distribution and installation tools provided with Python.
30
 
 
31
 
 
32
 
Key terms
33
 
=========
34
 
 
35
 
* ``pip`` is the preferred installer program. Starting with Python 2.7.9, it
36
 
  is included by default with the Python binary installers.
37
 
* a virtual environment is a semi-isolated Python environment that allows
38
 
  packages to be installed for use by a particular application, rather than
39
 
  being installed system wide
40
 
* ``virtualenv`` is a third party tools for creating virtual environments, it
41
 
  is defaults to installing ``pip`` into all created virtual environments.
42
 
* the `Python Packaging Index <https://pypi.python.org/pypi>`__ is a public
43
 
  repository of open source licensed packages made available for use by
44
 
  other Python users
45
 
* the `Python Packaging Authority
46
 
  <https://packaging.python.org/en/latest/future.html>`__ are the group of
47
 
  developers and documentation authors responsible for the maintenance and
48
 
  evolution of the standard packaging tools and the associated metadata and
49
 
  file format standards. They maintain a variety of tools, documentation
50
 
  and issue trackers on both `GitHub <https://github.com/pypa>`__ and
51
 
  `BitBucket <https://bitbucket.org/pypa/>`__.
52
 
* ``distutils`` is the original build and distribution system first added to
53
 
  the Python standard library in 1998. While direct use of ``distutils`` is
54
 
  being phased out, it still laid the foundation for the current packaging
55
 
  and distribution infrastructure, and it not only remains part of the
56
 
  standard library, but its name lives on in other ways (such as the name
57
 
  of the mailing list used to coordinate Python packaging standards
58
 
  development).
59
 
 
60
 
 
61
 
Basic usage
62
 
===========
63
 
 
64
 
The standard packaging tools are all designed to be used from the command
65
 
line.
66
 
 
67
 
The following command will install the latest version of a module and its
68
 
dependencies from the Python Packaging Index::
69
 
 
70
 
    python -m pip install SomePackage
71
 
 
72
 
.. note::
73
 
 
74
 
   For POSIX users (including Mac OS X and Linux users), the examples in
75
 
   this guide assume the use of a :term:`virtual environment`. You may install
76
 
   ``virtualenv`` to provide such environments using either pip
77
 
   (``pip install virtualenv``) or through your system package manager
78
 
   (commonly called ``virtualenv`` or ``python-virtualenv``).
79
 
 
80
 
   For Windows users, the examples in this guide assume that the option to
81
 
   adjust the system PATH environment variable was selected when installing
82
 
   Python.
83
 
 
84
 
It's also possible to specify an exact or minimum version directly on the
85
 
command line. When using comparator operators such as ``>``, ``<`` or some other
86
 
special character which get interpreted by shell, the package name and the
87
 
version should be enclosed within double quotes::
88
 
 
89
 
    python -m pip install SomePackage==1.0.4    # specific version
90
 
    python -m pip install "SomePackage>=1.0.4"  # minimum version
91
 
 
92
 
Normally, if a suitable module is already installed, attempting to install
93
 
it again will have no effect. Upgrading existing modules must be requested
94
 
explicitly::
95
 
 
96
 
    python -m pip install --upgrade SomePackage
97
 
 
98
 
More information and resources regarding ``pip`` and its capabilities can be
99
 
found in the `Python Packaging User Guide <https://packaging.python.org>`__.
100
 
 
101
 
.. seealso::
102
 
 
103
 
    `Python Packaging User Guide: Installing Python Distribution Packages
104
 
    <https://packaging.python.org/en/latest/installing.html#installing-python-distribution-packages>`__
105
 
 
106
 
 
107
 
How do I ...?
108
 
=============
109
 
 
110
 
These are quick answers or links for some common tasks.
111
 
 
112
 
... install ``pip`` in versions of Python prior to Python 2.7.9?
113
 
----------------------------------------------------------------
114
 
 
115
 
Python only started bundling ``pip`` with Python 2.7.9. For earlier versions,
116
 
``pip`` needs to be "bootstrapped" as described in the Python Packaging
117
 
User Guide.
118
 
 
119
 
.. seealso::
120
 
 
121
 
   `Python Packaging User Guide: Setup for Installing Distribution Packages
122
 
   <https://packaging.python.org/en/latest/installing.html#setup-for-installing-distribution-packages>`__
123
 
 
124
 
 
125
 
.. installing-per-user-installation:
126
 
 
127
 
... install packages just for the current user?
128
 
-----------------------------------------------
129
 
 
130
 
Passing the ``--user`` option to ``python -m pip install`` will install a
131
 
package just for the current user, rather than for all users of the system.
132
 
 
133
 
 
134
 
... install scientific Python packages?
135
 
---------------------------------------
136
 
 
137
 
A number of scientific Python packages have complex binary dependencies, and
138
 
aren't currently easy to install using ``pip`` directly. At this point in
139
 
time, it will often be easier for users to install these packages by
140
 
`other means
141
 
<https://packaging.python.org/en/latest/science.html>`__
142
 
rather than attempting to install them with ``pip``.
143
 
 
144
 
.. seealso::
145
 
 
146
 
   `Python Packaging User Guide: Installing Scientific Packages
147
 
   <https://packaging.python.org/en/latest/science.html>`__
148
 
 
149
 
 
150
 
... work with multiple versions of Python installed in parallel?
151
 
----------------------------------------------------------------
152
 
 
153
 
On Linux, Mac OS X and other POSIX systems, use the versioned Python commands
154
 
in combination with the ``-m`` switch to run the appropriate copy of
155
 
``pip``::
156
 
 
157
 
   python2   -m pip install SomePackage  # default Python 2
158
 
   python2.7 -m pip install SomePackage  # specifically Python 2.7
159
 
   python3   -m pip install SomePackage  # default Python 3
160
 
   python3.4 -m pip install SomePackage  # specifically Python 3.4
161
 
 
162
 
(appropriately versioned ``pip`` commands may also be available)
163
 
 
164
 
On Windows, use the ``py`` Python launcher in combination with the ``-m``
165
 
switch::
166
 
 
167
 
   py -2   -m pip install SomePackage  # default Python 2
168
 
   py -2.7 -m pip install SomePackage  # specifically Python 2.7
169
 
   py -3   -m pip install SomePackage  # default Python 3
170
 
   py -3.4 -m pip install SomePackage  # specifically Python 3.4
171
 
 
172
 
.. other questions:
173
 
 
174
 
   Once the Development & Deployment part of PPUG is fleshed out, some of
175
 
   those sections should be linked from new questions here (most notably,
176
 
   we should have a question about avoiding depending on PyPI that links to
177
 
   https://packaging.python.org/en/latest/deployment.html#pypi-mirrors-and-caches)
178
 
 
179
 
 
180
 
Common installation issues
181
 
==========================
182
 
 
183
 
Installing into the system Python on Linux
184
 
------------------------------------------
185
 
 
186
 
On Linux systems, a Python installation will typically be included as part
187
 
of the distribution. Installing into this Python installation requires
188
 
root access to the system, and may interfere with the operation of the
189
 
system package manager and other components of the system if a component
190
 
is unexpectedly upgraded using ``pip``.
191
 
 
192
 
On such systems, it is often better to use a virtual environment or a
193
 
per-user installation when installing packages with ``pip``.
194
 
 
195
 
 
196
 
Installing binary extensions
197
 
----------------------------
198
 
 
199
 
Python has typically relied heavily on source based distribution, with end
200
 
users being expected to compile extension modules from source as part of
201
 
the installation process.
202
 
 
203
 
With the introduction of support for the binary ``wheel`` format, and the
204
 
ability to publish wheels for at least Windows and Mac OS X through the
205
 
Python Packaging Index, this problem is expected to diminish over time,
206
 
as users are more regularly able to install pre-built extensions rather
207
 
than needing to build them themselves.
208
 
 
209
 
Some of the solutions for installing `scientific software
210
 
<https://packaging.python.org/en/latest/science.html>`__
211
 
that is not yet available as pre-built ``wheel`` files may also help with
212
 
obtaining other binary extensions without needing to build them locally.
213
 
 
214
 
.. seealso::
215
 
 
216
 
   `Python Packaging User Guide: Binary Extensions
217
 
   <https://packaging.python.org/en/latest/extensions.html>`__