Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 1 | |
| 2 | .. _tut-venv: |
| 3 | |
| 4 | ********************************* |
| 5 | Virtual Environments and Packages |
| 6 | ********************************* |
| 7 | |
| 8 | Introduction |
| 9 | ============ |
| 10 | |
| 11 | Python applications will often use packages and modules that don't |
| 12 | come as part of the standard library. Applications will sometimes |
| 13 | need a specific version of a library, because the application may |
| 14 | require that a particular bug has been fixed or the application may be |
| 15 | written using an obsolete version of the library's interface. |
| 16 | |
| 17 | This means it may not be possible for one Python installation to meet |
| 18 | the requirements of every application. If application A needs version |
| 19 | 1.0 of a particular module but application B needs version 2.0, then |
| 20 | the requirements are in conflict and installing either version 1.0 or 2.0 |
| 21 | will leave one application unable to run. |
| 22 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 23 | The solution for this problem is to create a :term:`virtual environment`, a |
| 24 | self-contained directory tree that contains a Python installation for a |
| 25 | particular version of Python, plus a number of additional packages. |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 26 | |
| 27 | Different applications can then use different virtual environments. |
| 28 | To resolve the earlier example of conflicting requirements, |
| 29 | application A can have its own virtual environment with version 1.0 |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 30 | installed while application B has another virtual environment with version 2.0. |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 31 | If application B requires a library be upgraded to version 3.0, this will |
| 32 | not affect application A's environment. |
| 33 | |
| 34 | |
| 35 | Creating Virtual Environments |
| 36 | ============================= |
| 37 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 38 | The module used to create and manage virtual environments is called |
| 39 | :mod:`venv`. :mod:`venv` will usually install the most recent version of |
| 40 | Python that you have available. If you have multiple versions of Python on your |
| 41 | system, you can select a specific Python version by running ``python3`` or |
| 42 | whichever version you want. |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 43 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 44 | To create a virtual environment, decide upon a directory where you want to |
| 45 | place it, and run the :mod:`venv` module as a script with the directory path:: |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 46 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 47 | python3 -m venv tutorial-env |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 48 | |
| 49 | This will create the ``tutorial-env`` directory if it doesn't exist, |
| 50 | and also create directories inside it containing a copy of the Python |
Andrew Kuchling | d004071 | 2015-06-08 18:17:06 -0400 | [diff] [blame] | 51 | interpreter, the standard library, and various supporting files. |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 52 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 53 | Once you've created a virtual environment, you may activate it. |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 54 | |
| 55 | On Windows, run:: |
| 56 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 57 | tutorial-env\Scripts\activate.bat |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 58 | |
| 59 | On Unix or MacOS, run:: |
| 60 | |
| 61 | source tutorial-env/bin/activate |
| 62 | |
| 63 | (This script is written for the bash shell. If you use the |
| 64 | :program:`csh` or :program:`fish` shells, there are alternate |
| 65 | ``activate.csh`` and ``activate.fish`` scripts you should use |
| 66 | instead.) |
| 67 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 68 | Activating the virtual environment will change your shell's prompt to show what |
| 69 | virtual environment you're using, and modify the environment so that running |
| 70 | ``python`` will get you that particular version and installation of Python. |
| 71 | For example: |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 72 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 73 | .. code-block:: bash |
| 74 | |
| 75 | $ source ~/envs/tutorial-env/bin/activate |
| 76 | (tutorial-env) $ python |
| 77 | Python 3.5.1 (default, May 6 2016, 10:59:36) |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 78 | ... |
| 79 | >>> import sys |
| 80 | >>> sys.path |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 81 | ['', '/usr/local/lib/python35.zip', ..., |
| 82 | '~/envs/tutorial-env/lib/python3.5/site-packages'] |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 83 | >>> |
| 84 | |
| 85 | |
| 86 | Managing Packages with pip |
| 87 | ========================== |
| 88 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 89 | You can install, upgrade, and remove packages using a program called |
| 90 | :program:`pip`. By default ``pip`` will install packages from the Python |
Stéphane Wirtel | 19177fb | 2018-05-15 20:58:35 +0200 | [diff] [blame] | 91 | Package Index, <https://pypi.org>. You can browse the Python |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 92 | Package Index by going to it in your web browser, or you can use ``pip``'s |
| 93 | limited search feature: |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 94 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 95 | .. code-block:: bash |
| 96 | |
| 97 | (tutorial-env) $ pip search astronomy |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 98 | skyfield - Elegant astronomy for Python |
| 99 | gary - Galactic astronomy and gravitational dynamics. |
| 100 | novas - The United States Naval Observatory NOVAS astronomy library |
| 101 | astroobs - Provides astronomy ephemeris to plan telescope observations |
| 102 | PyAstronomy - A collection of astronomy related tools for Python. |
| 103 | ... |
| 104 | |
| 105 | ``pip`` has a number of subcommands: "search", "install", "uninstall", |
| 106 | "freeze", etc. (Consult the :ref:`installing-index` guide for |
| 107 | complete documentation for ``pip``.) |
| 108 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 109 | You can install the latest version of a package by specifying a package's name: |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 110 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 111 | .. code-block:: bash |
| 112 | |
| 113 | (tutorial-env) $ pip install novas |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 114 | Collecting novas |
| 115 | Downloading novas-3.1.1.3.tar.gz (136kB) |
| 116 | Installing collected packages: novas |
| 117 | Running setup.py install for novas |
| 118 | Successfully installed novas-3.1.1.3 |
| 119 | |
| 120 | You can also install a specific version of a package by giving the |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 121 | package name followed by ``==`` and the version number: |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 122 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 123 | .. code-block:: bash |
| 124 | |
| 125 | (tutorial-env) $ pip install requests==2.6.0 |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 126 | Collecting requests==2.6.0 |
| 127 | Using cached requests-2.6.0-py2.py3-none-any.whl |
| 128 | Installing collected packages: requests |
| 129 | Successfully installed requests-2.6.0 |
| 130 | |
| 131 | If you re-run this command, ``pip`` will notice that the requested |
| 132 | version is already installed and do nothing. You can supply a |
| 133 | different version number to get that version, or you can run ``pip |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 134 | install --upgrade`` to upgrade the package to the latest version: |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 135 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 136 | .. code-block:: bash |
| 137 | |
| 138 | (tutorial-env) $ pip install --upgrade requests |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 139 | Collecting requests |
| 140 | Installing collected packages: requests |
| 141 | Found existing installation: requests 2.6.0 |
| 142 | Uninstalling requests-2.6.0: |
| 143 | Successfully uninstalled requests-2.6.0 |
| 144 | Successfully installed requests-2.7.0 |
| 145 | |
| 146 | ``pip uninstall`` followed by one or more package names will remove the |
| 147 | packages from the virtual environment. |
| 148 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 149 | ``pip show`` will display information about a particular package: |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 150 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 151 | .. code-block:: bash |
| 152 | |
| 153 | (tutorial-env) $ pip show requests |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 154 | --- |
| 155 | Metadata-Version: 2.0 |
| 156 | Name: requests |
| 157 | Version: 2.7.0 |
| 158 | Summary: Python HTTP for Humans. |
| 159 | Home-page: http://python-requests.org |
| 160 | Author: Kenneth Reitz |
| 161 | Author-email: me@kennethreitz.com |
| 162 | License: Apache 2.0 |
| 163 | Location: /Users/akuchling/envs/tutorial-env/lib/python3.4/site-packages |
| 164 | Requires: |
| 165 | |
| 166 | ``pip list`` will display all of the packages installed in the virtual |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 167 | environment: |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 168 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 169 | .. code-block:: bash |
| 170 | |
| 171 | (tutorial-env) $ pip list |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 172 | novas (3.1.1.3) |
| 173 | numpy (1.9.2) |
| 174 | pip (7.0.3) |
| 175 | requests (2.7.0) |
| 176 | setuptools (16.0) |
| 177 | |
| 178 | ``pip freeze`` will produce a similar list of the installed packages, |
| 179 | but the output uses the format that ``pip install`` expects. |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 180 | A common convention is to put this list in a ``requirements.txt`` file: |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 181 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 182 | .. code-block:: bash |
| 183 | |
| 184 | (tutorial-env) $ pip freeze > requirements.txt |
| 185 | (tutorial-env) $ cat requirements.txt |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 186 | novas==3.1.1.3 |
| 187 | numpy==1.9.2 |
| 188 | requests==2.7.0 |
| 189 | |
| 190 | The ``requirements.txt`` can then be committed to version control and |
| 191 | shipped as part of an application. Users can then install all the |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 192 | necessary packages with ``install -r``: |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 193 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 194 | .. code-block:: bash |
| 195 | |
| 196 | (tutorial-env) $ pip install -r requirements.txt |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 197 | Collecting novas==3.1.1.3 (from -r requirements.txt (line 1)) |
| 198 | ... |
| 199 | Collecting numpy==1.9.2 (from -r requirements.txt (line 2)) |
| 200 | ... |
| 201 | Collecting requests==2.7.0 (from -r requirements.txt (line 3)) |
| 202 | ... |
| 203 | Installing collected packages: novas, numpy, requests |
| 204 | Running setup.py install for novas |
| 205 | Successfully installed novas-3.1.1.3 numpy-1.9.2 requests-2.7.0 |
| 206 | |
| 207 | ``pip`` has many more options. Consult the :ref:`installing-index` |
| 208 | guide for complete documentation for ``pip``. When you've written |
Tal Einat | f330d53 | 2015-06-09 18:40:16 +0300 | [diff] [blame] | 209 | a package and want to make it available on the Python Package Index, |
Andrew Kuchling | dd15b36 | 2015-06-08 17:35:45 -0400 | [diff] [blame] | 210 | consult the :ref:`distributing-index` guide. |