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. |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 47 | * the `Python Package Index <https://pypi.python.org/pypi>`__ is a public |
| 48 | repository of open source licensed packages made available for use by |
| 49 | other Python users |
| 50 | * the `Python Packaging Authority |
| 51 | <http://packaging.python.org/en/latest/future.html>`__ are the group of |
| 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 |
| 73 | dependencies from the Python Package Index:: |
| 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 |
| 87 | command line:: |
| 88 | |
Nick Coghlan | 1d52096 | 2014-09-06 20:38:23 +1000 | [diff] [blame^] | 89 | python -m pip install SomePackage==1.0.4 # specific version |
| 90 | python -m pip install 'SomePackage>=1.0.4' # minimum version |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 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 | |
Nick Coghlan | 1d52096 | 2014-09-06 20:38:23 +1000 | [diff] [blame^] | 96 | python -m pip install --upgrade SomePackage |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 97 | |
| 98 | More information and resources regarding ``pip`` and its capabilities can be |
| 99 | found in the `Python Packaging User Guide <http://packaging.python.org>`__. |
| 100 | |
| 101 | ``pyvenv`` has its own documentation at :ref:`scripts-pyvenv`. Installing |
| 102 | into an active virtual environment uses the commands shown above. |
| 103 | |
| 104 | .. seealso:: |
| 105 | |
| 106 | `Python Packaging User Guide: Installing Python packages |
| 107 | <http://packaging.python.org/en/latest/tutorial.html#installing-python-packages>`__ |
| 108 | |
| 109 | |
| 110 | How do I ...? |
| 111 | ============= |
| 112 | |
| 113 | These are quick answers or links for some common tasks. |
| 114 | |
| 115 | ... install ``pip`` in versions of Python prior to Python 3.4? |
| 116 | -------------------------------------------------------------- |
| 117 | |
| 118 | Python only started bundling ``pip`` with Python 3.4. For earlier versions, |
| 119 | ``pip`` needs to be "bootstrapped" as described in the Python Packaging |
| 120 | User Guide. |
| 121 | |
| 122 | .. seealso:: |
| 123 | |
| 124 | `Python Packaging User Guide: Installing the Tools |
| 125 | <http://packaging.python.org/en/latest/tutorial.html#installing-the-tools>`__ |
| 126 | |
| 127 | |
| 128 | .. installing-per-user-installation: |
| 129 | |
| 130 | ... install packages just for the current user? |
| 131 | ----------------------------------------------- |
| 132 | |
Nick Coghlan | 1d52096 | 2014-09-06 20:38:23 +1000 | [diff] [blame^] | 133 | Passing the ``--user`` option to ``python -m pip install`` will install a |
| 134 | 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] | 135 | |
| 136 | |
| 137 | ... install scientific Python packages? |
| 138 | --------------------------------------- |
| 139 | |
| 140 | A number of scientific Python packages have complex binary dependencies, and |
| 141 | aren't currently easy to install using ``pip`` directly. At this point in |
| 142 | time, it will often be easier for users to install these packages by |
| 143 | `other means |
| 144 | <http://packaging.python.org/en/latest/platforms.html#installing-scientific-packages>`__ |
| 145 | rather than attempting to install them with ``pip``. |
| 146 | |
| 147 | .. seealso:: |
| 148 | |
| 149 | `Python Packaging User Guide: Installing Scientific Packages |
| 150 | <http://packaging.python.org/en/latest/platforms.html#installing-scientific-packages>`__ |
| 151 | |
| 152 | |
| 153 | ... work with multiple versions of Python installed in parallel? |
| 154 | ---------------------------------------------------------------- |
| 155 | |
| 156 | On Linux, Mac OS X and other POSIX systems, use the versioned Python commands |
| 157 | in combination with the ``-m`` switch to run the appropriate copy of |
| 158 | ``pip``:: |
| 159 | |
| 160 | python2 -m pip install SomePackage # default Python 2 |
| 161 | python2.7 -m pip install SomePackage # specifically Python 2.7 |
| 162 | python3 -m pip install SomePackage # default Python 3 |
| 163 | python3.4 -m pip install SomePackage # specifically Python 3.4 |
| 164 | |
| 165 | (appropriately versioned ``pip`` commands may also be available) |
| 166 | |
| 167 | On Windows, use the ``py`` Python launcher in combination with the ``-m`` |
| 168 | switch:: |
| 169 | |
| 170 | py -2 -m pip install SomePackage # default Python 2 |
| 171 | py -2.7 -m pip install SomePackage # specifically Python 2.7 |
| 172 | py -3 -m pip install SomePackage # default Python 3 |
| 173 | py -3.4 -m pip install SomePackage # specifically Python 3.4 |
| 174 | |
| 175 | .. other questions: |
| 176 | |
| 177 | Once the Development & Deployment part of PPUG is fleshed out, some of |
| 178 | those sections should be linked from new questions here (most notably, |
| 179 | we should have a question about avoiding depending on PyPI that links to |
| 180 | http://packaging.python.org/en/latest/deployment.html#pypi-mirrors-and-caches) |
| 181 | |
| 182 | |
| 183 | Common installation issues |
| 184 | ========================== |
| 185 | |
| 186 | Installing into the system Python on Linux |
| 187 | ------------------------------------------ |
| 188 | |
| 189 | On Linux systems, a Python installation will typically be included as part |
| 190 | of the distribution. Installing into this Python installation requires |
| 191 | root access to the system, and may interfere with the operation of the |
| 192 | system package manager and other components of the system if a component |
| 193 | is unexpectedly upgraded using ``pip``. |
| 194 | |
| 195 | On such systems, it is often better to use a virtual environment or a |
| 196 | per-user installation when installing packages with ``pip``. |
| 197 | |
| 198 | |
| 199 | Installing binary extensions |
| 200 | ---------------------------- |
| 201 | |
| 202 | Python has typically relied heavily on source based distribution, with end |
| 203 | users being expected to compile extension modules from source as part of |
| 204 | the installation process. |
| 205 | |
| 206 | With the introduction of support for the binary ``wheel`` format, and the |
| 207 | ability to publish wheels for at least Windows and Mac OS X through the |
| 208 | Python Package Index, this problem is expected to diminish over time, |
| 209 | as users are more regularly able to install pre-built extensions rather |
| 210 | than needing to build them themselves. |
| 211 | |
| 212 | Some of the solutions for installing `scientific software |
| 213 | <http://packaging.python.org/en/latest/platforms.html#installing-scientific-packages>`__ |
| 214 | that is not yet available as pre-built ``wheel`` files may also help with |
| 215 | obtaining other binary extensions without needing to build them locally. |
| 216 | |
| 217 | .. seealso:: |
| 218 | |
| 219 | `Python Packaging User Guide: Binary Extensions |
| 220 | <http://packaging.python.org/en/latest/extensions.html>`__ |