Debian Codegraph @

Doc/installing/index.rst

raw
1 .. highlight:: shell
2
3 .. _installing-index:
4
5 *************************
6 Installing Python modules
7 *************************
8
9 As a popular open source development project, Python has an active
10 supporting community of contributors and users that also make their software
11 available for other Python developers to use under open-source license terms.
12
13 This allows Python users to share and collaborate effectively, benefiting
14 from the solutions others have already created to common (and sometimes
15 even rare!) problems, as well as potentially contributing their own
16 solutions to the common pool.
17
18 This guide covers the installation part of the process. For a guide to
19 creating and sharing your own Python projects, refer to the
20 `Python packaging user guide`_.
21
22 .. _Python Packaging User Guide: https://packaging.python.org/en/latest/tutorials/packaging-projects/
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 * :program:`pip` is the preferred installer program. 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 * ``venv`` is the standard tool for creating virtual environments.
41 It defaults to installing :program:`pip` into all created virtual environments.
42 * ``virtualenv`` is a third-party alternative (and predecessor) to
43 ``venv``.
44 * The `Python Package Index (PyPI) <https://pypi.org>`__ is a public
45 repository of open source licensed packages made available for use by
46 other Python users.
47 * The `Python Packaging Authority
48 <https://www.pypa.io/>`__ is the group of
49 developers and documentation authors responsible for the maintenance and
50 evolution of the standard packaging tools and the associated metadata and
51 file format standards. They maintain a variety of tools, documentation,
52 and issue trackers on `GitHub <https://github.com/pypa>`__.
53
54 .. versionchanged:: 3.5
55 The use of ``venv`` is now recommended for creating virtual environments.
56
57 .. seealso::
58
59 `Python Packaging User Guide: Creating and using virtual environments
60 <https://packaging.python.org/installing/#creating-virtual-environments>`__
61
62
63 Basic usage
64 ===========
65
66 The standard packaging tools are all designed to be used from the command
67 line.
68
69 The following command will install the latest version of a module and its
70 dependencies from PyPI::
71
72 python -m pip install SomePackage
73
74 .. note::
75
76 For POSIX users (including macOS and Linux users), the examples in
77 this guide assume the use of a :term:`virtual environment`.
78
79 For Windows users, the examples in this guide assume that the option to
80 adjust the system PATH environment variable was selected when installing
81 Python.
82
83 It's also possible to specify an exact or minimum version directly on the
84 command line. When using comparator operators such as ``>``, ``<`` or some other
85 special character which get interpreted by shell, the package name and the
86 version should be enclosed within double quotes::
87
88 python -m pip install SomePackage==1.0.4 # specific version
89 python -m pip install "SomePackage>=1.0.4" # minimum version
90
91 Normally, if a suitable module is already installed, attempting to install
92 it again will have no effect. Upgrading existing modules must be requested
93 explicitly::
94
95 python -m pip install --upgrade SomePackage
96
97 More information and resources regarding :program:`pip` and its capabilities can be
98 found in the `Python Packaging User Guide <https://packaging.python.org>`__.
99
100 Creation of virtual environments is done through the :mod:`venv` module.
101 Installing packages into an active virtual environment uses the commands shown
102 above.
103
104 .. seealso::
105
106 `Python Packaging User Guide: Installing Python Distribution Packages
107 <https://packaging.python.org/installing/>`__
108
109
110 How do I ...?
111 =============
112
113 These are quick answers or links for some common tasks.
114
115 .. installing-per-user-installation:
116
117 ... install packages just for the current user?
118 -----------------------------------------------
119
120 Passing the ``--user`` option to ``python -m pip install`` will install a
121 package just for the current user, rather than for all users of the system.
122
123
124 ... install scientific Python packages?
125 ---------------------------------------
126
127 A number of scientific Python packages have complex binary dependencies, and
128 aren't currently easy to install using :program:`pip` directly.
129 It will often be easier for users to install these packages by
130 `other means <https://packaging.python.org/science/>`__
131 rather than attempting to install them with :program:`pip`.
132
133 .. seealso::
134
135 `Python Packaging User Guide: Installing Scientific Packages
136 <https://packaging.python.org/science/>`__
137
138
139 ... work with multiple versions of Python installed in parallel?
140 ----------------------------------------------------------------
141
142 On Linux, macOS, and other POSIX systems, use the versioned Python commands
143 in combination with the ``-m`` switch to run the appropriate copy of
144 :program:`pip`::
145
146 python3 -m pip install SomePackage # default Python 3
147 python3.14 -m pip install SomePackage # specifically Python 3.14
148
149 Appropriately versioned :program:`pip` commands may also be available.
150
151 On Windows, use the :program:`py` Python launcher in combination with the ``-m``
152 switch::
153
154 py -3 -m pip install SomePackage # default Python 3
155 py -3.14 -m pip install SomePackage # specifically Python 3.14
156
157 .. other questions:
158
159 Once the Development & Deployment part of PPUG is fleshed out, some of
160 those sections should be linked from new questions here (most notably,
161 we should have a question about avoiding depending on PyPI that links to
162 https://packaging.python.org/en/latest/guides/index-mirrors-and-caches/)
163
164
165 Common installation issues
166 ==========================
167
168 Installing into the system Python on Linux
169 ------------------------------------------
170
171 On Linux systems, a Python installation will typically be included as part
172 of the distribution. Installing into this Python installation requires
173 root access to the system, and may interfere with the operation of the
174 system package manager and other components of the system if a component
175 is unexpectedly upgraded using :program:`pip`.
176
177 On such systems, it is often better to use a virtual environment or a
178 per-user installation when installing packages with :program:`pip`.
179
180
181 Pip not installed
182 -----------------
183
184 It is possible that :program:`pip` does not get installed by default. One potential fix is::
185
186 python -m ensurepip --default-pip
187
188 There are also additional resources for `installing pip
189 <https://packaging.python.org/en/latest/tutorials/installing-packages/#ensure-pip-setuptools-and-wheel-are-up-to-date>`__.
190
191
192 Installing binary extensions
193 ----------------------------
194
195 Python once relied heavily on source-based distribution, with end
196 users being expected to compile extension modules from source as part of
197 the installation process.
198
199 With the introduction of the binary wheel format, and the
200 ability to publish wheels through PyPI, this problem is diminishing,
201 as users are more regularly able to install pre-built extensions rather
202 than needing to build them themselves.
203
204 Some of the solutions for installing `scientific software
205 <https://packaging.python.org/science/>`__
206 that are not yet available as pre-built wheel files may also help with
207 obtaining other binary extensions without needing to build them locally.
208
209 .. seealso::
210
211 `Python Packaging User Guide: Binary Extensions
212 <https://packaging.python.org/extensions/>`__