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