Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 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 3.4, 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 | * ``pyvenv`` is the standard tool for creating virtual environments, and has |
| 41 | been part of Python since Python 3.3. Starting with Python 3.4, it |
| 42 | defaults to installing ``pip`` into all created virtual environments |
Nick Coghlan | 1d52096 | 2014-09-06 20:38:23 +1000 | [diff] [blame] | 43 | * ``virtualenv`` is a third party alternative (and predecessor) to |
| 44 | ``pyvenv``. It allows virtual environments to be used on versions of |
| 45 | Python prior to 3.4, which either don't provide ``pyvenv`` at all, or |
| 46 | aren't able to automatically install ``pip`` into created environments. |
Nick Coghlan | 5c4fbd5 | 2014-10-04 21:11:25 +1000 | [diff] [blame] | 47 | * the `Python Packaging Index <https://pypi.python.org/pypi>`__ is a public |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 48 | repository of open source licensed packages made available for use by |
| 49 | other Python users |
| 50 | * the `Python Packaging Authority |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame^] | 51 | <https://www.pypa.io/en/latest/>`__ are the group of |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 52 | developers and documentation authors responsible for the maintenance and |
| 53 | evolution of the standard packaging tools and the associated metadata and |
| 54 | file format standards. They maintain a variety of tools, documentation |
| 55 | and issue trackers on both `GitHub <https://github.com/pypa>`__ and |
| 56 | `BitBucket <https://bitbucket.org/pypa/>`__. |
| 57 | * ``distutils`` is the original build and distribution system first added to |
| 58 | the Python standard library in 1998. While direct use of ``distutils`` is |
| 59 | being phased out, it still laid the foundation for the current packaging |
| 60 | and distribution infrastructure, and it not only remains part of the |
| 61 | standard library, but its name lives on in other ways (such as the name |
| 62 | of the mailing list used to coordinate Python packaging standards |
| 63 | development). |
| 64 | |
| 65 | |
| 66 | Basic usage |
| 67 | =========== |
| 68 | |
| 69 | The standard packaging tools are all designed to be used from the command |
Nick Coghlan | 1d52096 | 2014-09-06 20:38:23 +1000 | [diff] [blame] | 70 | line. |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 71 | |
| 72 | The following command will install the latest version of a module and its |
Nick Coghlan | 5c4fbd5 | 2014-10-04 21:11:25 +1000 | [diff] [blame] | 73 | dependencies from the Python Packaging Index:: |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 74 | |
Nick Coghlan | 1d52096 | 2014-09-06 20:38:23 +1000 | [diff] [blame] | 75 | python -m pip install SomePackage |
| 76 | |
| 77 | .. note:: |
| 78 | |
| 79 | For POSIX users (including Mac OS X and Linux users), the examples in |
| 80 | this guide assume the use of a :term:`virtual environment`. |
| 81 | |
| 82 | For Windows users, the examples in this guide assume that the option to |
| 83 | adjust the system PATH environment variable was selected when installing |
| 84 | Python. |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 85 | |
| 86 | It's also possible to specify an exact or minimum version directly on the |
Senthil Kumaran | 76d9a6b | 2016-01-17 18:42:13 -0800 | [diff] [blame] | 87 | command line. When using comparator operators such as ``>``, ``<`` or some other |
| 88 | special character which get interpreted by shell, the package name and the |
| 89 | version should be enclosed within double quotes:: |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 90 | |
Nick Coghlan | 1d52096 | 2014-09-06 20:38:23 +1000 | [diff] [blame] | 91 | python -m pip install SomePackage==1.0.4 # specific version |
Senthil Kumaran | 76d9a6b | 2016-01-17 18:42:13 -0800 | [diff] [blame] | 92 | python -m pip install "SomePackage>=1.0.4" # minimum version |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 93 | |
| 94 | Normally, if a suitable module is already installed, attempting to install |
| 95 | it again will have no effect. Upgrading existing modules must be requested |
| 96 | explicitly:: |
| 97 | |
Nick Coghlan | 1d52096 | 2014-09-06 20:38:23 +1000 | [diff] [blame] | 98 | python -m pip install --upgrade SomePackage |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 99 | |
| 100 | More information and resources regarding ``pip`` and its capabilities can be |
Georg Brandl | e73778c | 2014-10-29 08:36:35 +0100 | [diff] [blame] | 101 | found in the `Python Packaging User Guide <https://packaging.python.org>`__. |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 102 | |
| 103 | ``pyvenv`` has its own documentation at :ref:`scripts-pyvenv`. Installing |
| 104 | into an active virtual environment uses the commands shown above. |
| 105 | |
| 106 | .. seealso:: |
| 107 | |
Nick Coghlan | 5c4fbd5 | 2014-10-04 21:11:25 +1000 | [diff] [blame] | 108 | `Python Packaging User Guide: Installing Python Distribution Packages |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame^] | 109 | <https://packaging.python.org/en/latest/installing/>`__ |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 110 | |
| 111 | |
| 112 | How do I ...? |
| 113 | ============= |
| 114 | |
| 115 | These are quick answers or links for some common tasks. |
| 116 | |
| 117 | ... install ``pip`` in versions of Python prior to Python 3.4? |
| 118 | -------------------------------------------------------------- |
| 119 | |
| 120 | Python only started bundling ``pip`` with Python 3.4. For earlier versions, |
| 121 | ``pip`` needs to be "bootstrapped" as described in the Python Packaging |
| 122 | User Guide. |
| 123 | |
| 124 | .. seealso:: |
| 125 | |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame^] | 126 | `Python Packaging User Guide: Requirements for Installing Packages |
| 127 | <https://packaging.python.org/en/latest/installing/#requirements-for-installing-packages>`__ |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 128 | |
| 129 | |
| 130 | .. installing-per-user-installation: |
| 131 | |
| 132 | ... install packages just for the current user? |
| 133 | ----------------------------------------------- |
| 134 | |
Nick Coghlan | 1d52096 | 2014-09-06 20:38:23 +1000 | [diff] [blame] | 135 | Passing the ``--user`` option to ``python -m pip install`` will install a |
| 136 | package just for the current user, rather than for all users of the system. |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 137 | |
| 138 | |
| 139 | ... install scientific Python packages? |
| 140 | --------------------------------------- |
| 141 | |
| 142 | A number of scientific Python packages have complex binary dependencies, and |
| 143 | aren't currently easy to install using ``pip`` directly. At this point in |
| 144 | time, it will often be easier for users to install these packages by |
| 145 | `other means |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame^] | 146 | <https://packaging.python.org/en/latest/science/>`__ |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 147 | rather than attempting to install them with ``pip``. |
| 148 | |
| 149 | .. seealso:: |
| 150 | |
| 151 | `Python Packaging User Guide: Installing Scientific Packages |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame^] | 152 | <https://packaging.python.org/en/latest/science/>`__ |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 153 | |
| 154 | |
| 155 | ... work with multiple versions of Python installed in parallel? |
| 156 | ---------------------------------------------------------------- |
| 157 | |
| 158 | On Linux, Mac OS X and other POSIX systems, use the versioned Python commands |
| 159 | in combination with the ``-m`` switch to run the appropriate copy of |
| 160 | ``pip``:: |
| 161 | |
| 162 | python2 -m pip install SomePackage # default Python 2 |
| 163 | python2.7 -m pip install SomePackage # specifically Python 2.7 |
| 164 | python3 -m pip install SomePackage # default Python 3 |
| 165 | python3.4 -m pip install SomePackage # specifically Python 3.4 |
| 166 | |
| 167 | (appropriately versioned ``pip`` commands may also be available) |
| 168 | |
| 169 | On Windows, use the ``py`` Python launcher in combination with the ``-m`` |
| 170 | switch:: |
| 171 | |
| 172 | py -2 -m pip install SomePackage # default Python 2 |
| 173 | py -2.7 -m pip install SomePackage # specifically Python 2.7 |
| 174 | py -3 -m pip install SomePackage # default Python 3 |
| 175 | py -3.4 -m pip install SomePackage # specifically Python 3.4 |
| 176 | |
| 177 | .. other questions: |
| 178 | |
| 179 | Once the Development & Deployment part of PPUG is fleshed out, some of |
| 180 | those sections should be linked from new questions here (most notably, |
| 181 | we should have a question about avoiding depending on PyPI that links to |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame^] | 182 | https://packaging.python.org/en/latest/mirrors/) |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 183 | |
| 184 | |
| 185 | Common installation issues |
| 186 | ========================== |
| 187 | |
| 188 | Installing into the system Python on Linux |
| 189 | ------------------------------------------ |
| 190 | |
| 191 | On Linux systems, a Python installation will typically be included as part |
| 192 | of the distribution. Installing into this Python installation requires |
| 193 | root access to the system, and may interfere with the operation of the |
| 194 | system package manager and other components of the system if a component |
| 195 | is unexpectedly upgraded using ``pip``. |
| 196 | |
| 197 | On such systems, it is often better to use a virtual environment or a |
| 198 | per-user installation when installing packages with ``pip``. |
| 199 | |
| 200 | |
| 201 | Installing binary extensions |
| 202 | ---------------------------- |
| 203 | |
| 204 | Python has typically relied heavily on source based distribution, with end |
| 205 | users being expected to compile extension modules from source as part of |
| 206 | the installation process. |
| 207 | |
| 208 | With the introduction of support for the binary ``wheel`` format, and the |
| 209 | ability to publish wheels for at least Windows and Mac OS X through the |
Nick Coghlan | 5c4fbd5 | 2014-10-04 21:11:25 +1000 | [diff] [blame] | 210 | Python Packaging Index, this problem is expected to diminish over time, |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 211 | as users are more regularly able to install pre-built extensions rather |
| 212 | than needing to build them themselves. |
| 213 | |
| 214 | Some of the solutions for installing `scientific software |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame^] | 215 | <https://packaging.python.org/en/latest/science/>`__ |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 216 | that is not yet available as pre-built ``wheel`` files may also help with |
| 217 | obtaining other binary extensions without needing to build them locally. |
| 218 | |
| 219 | .. seealso:: |
| 220 | |
| 221 | `Python Packaging User Guide: Binary Extensions |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame^] | 222 | <https://packaging.python.org/en/latest/extensions/>`__ |