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.
99
100``pip`` has a number of subcommands: "install", "uninstall",
101"freeze", etc.  (Consult the :ref:`installing-index` guide for
102complete documentation for ``pip``.)
103
104You can install the latest version of a package by specifying a package's name:
105
106.. code-block:: bash
107
108  (tutorial-env) $ pip install novas
109  Collecting novas
110    Downloading novas-3.1.1.3.tar.gz (136kB)
111  Installing collected packages: novas
112    Running setup.py install for novas
113  Successfully installed novas-3.1.1.3
114
115You can also install a specific version of a package by giving the
116package name  followed by ``==`` and the version number:
117
118.. code-block:: bash
119
120  (tutorial-env) $ pip install requests==2.6.0
121  Collecting requests==2.6.0
122    Using cached requests-2.6.0-py2.py3-none-any.whl
123  Installing collected packages: requests
124  Successfully installed requests-2.6.0
125
126If you re-run this command, ``pip`` will notice that the requested
127version is already installed and do nothing.  You can supply a
128different version number to get that version, or you can run ``pip
129install --upgrade`` to upgrade the package to the latest version:
130
131.. code-block:: bash
132
133  (tutorial-env) $ pip install --upgrade requests
134  Collecting requests
135  Installing collected packages: requests
136    Found existing installation: requests 2.6.0
137      Uninstalling requests-2.6.0:
138        Successfully uninstalled requests-2.6.0
139  Successfully installed requests-2.7.0
140
141``pip uninstall`` followed by one or more package names will remove the
142packages from the virtual environment.
143
144``pip show`` will display information about a particular package:
145
146.. code-block:: bash
147
148  (tutorial-env) $ pip show requests
149  ---
150  Metadata-Version: 2.0
151  Name: requests
152  Version: 2.7.0
153  Summary: Python HTTP for Humans.
154  Home-page: http://python-requests.org
155  Author: Kenneth Reitz
156  Author-email: me@kennethreitz.com
157  License: Apache 2.0
158  Location: /Users/akuchling/envs/tutorial-env/lib/python3.4/site-packages
159  Requires:
160
161``pip list`` will display all of the packages installed in the virtual
162environment:
163
164.. code-block:: bash
165
166  (tutorial-env) $ pip list
167  novas (3.1.1.3)
168  numpy (1.9.2)
169  pip (7.0.3)
170  requests (2.7.0)
171  setuptools (16.0)
172
173``pip freeze`` will produce a similar list of the installed packages,
174but the output uses the format that ``pip install`` expects.
175A common convention is to put this list in a ``requirements.txt`` file:
176
177.. code-block:: bash
178
179  (tutorial-env) $ pip freeze > requirements.txt
180  (tutorial-env) $ cat requirements.txt
181  novas==3.1.1.3
182  numpy==1.9.2
183  requests==2.7.0
184
185The ``requirements.txt`` can then be committed to version control and
186shipped as part of an application.  Users can then install all the
187necessary packages with ``install -r``:
188
189.. code-block:: bash
190
191  (tutorial-env) $ pip install -r requirements.txt
192  Collecting novas==3.1.1.3 (from -r requirements.txt (line 1))
193    ...
194  Collecting numpy==1.9.2 (from -r requirements.txt (line 2))
195    ...
196  Collecting requests==2.7.0 (from -r requirements.txt (line 3))
197    ...
198  Installing collected packages: novas, numpy, requests
199    Running setup.py install for novas
200  Successfully installed novas-3.1.1.3 numpy-1.9.2 requests-2.7.0
201
202``pip`` has many more options.  Consult the :ref:`installing-index`
203guide for complete documentation for ``pip``.  When you've written
204a package and want to make it available on the Python Package Index,
205consult the :ref:`distributing-index` guide.
206