| 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/>`__ |