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
53Once you've created a virtual environment, you may activate it.
54
55On Windows, run::
56
57  tutorial-env\Scripts\activate.bat
58
59On 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
66instead.)
67
68Activating the virtual environment will change your shell's prompt to show what
69virtual environment you're using, and modify the environment so that running
70``python`` will get you that particular version and installation of Python.
71For example:
72
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)
78    ...
79  >>> import sys
80  >>> sys.path
81  ['', '/usr/local/lib/python35.zip', ...,
82  '~/envs/tutorial-env/lib/python3.5/site-packages']
83  >>>
84
85
86Managing Packages with pip
87==========================
88
89You can install, upgrade, and remove packages using a program called
90:program:`pip`.  By default ``pip`` will install packages from the Python
91Package Index, <https://pypi.org>.  You can browse the Python
92Package Index by going to it in your web browser, or you can use ``pip``'s
93limited search feature:
94
95.. code-block:: bash
96
97  (tutorial-env) $ pip search astronomy
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
107complete documentation for ``pip``.)
108
109You can install the latest version of a package by specifying a package's name:
110
111.. code-block:: bash
112
113  (tutorial-env) $ pip install novas
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
120You can also install a specific version of a package by giving the
121package name  followed by ``==`` and the version number:
122
123.. code-block:: bash
124
125  (tutorial-env) $ pip install requests==2.6.0
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
131If you re-run this command, ``pip`` will notice that the requested
132version is already installed and do nothing.  You can supply a
133different version number to get that version, or you can run ``pip
134install --upgrade`` to upgrade the package to the latest version:
135
136.. code-block:: bash
137
138  (tutorial-env) $ pip install --upgrade requests
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
147packages from the virtual environment.
148
149``pip show`` will display information about a particular package:
150
151.. code-block:: bash
152
153  (tutorial-env) $ pip show requests
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
167environment:
168
169.. code-block:: bash
170
171  (tutorial-env) $ pip list
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,
179but the output uses the format that ``pip install`` expects.
180A common convention is to put this list in a ``requirements.txt`` file:
181
182.. code-block:: bash
183
184  (tutorial-env) $ pip freeze > requirements.txt
185  (tutorial-env) $ cat requirements.txt
186  novas==3.1.1.3
187  numpy==1.9.2
188  requests==2.7.0
189
190The ``requirements.txt`` can then be committed to version control and
191shipped as part of an application.  Users can then install all the
192necessary packages with ``install -r``:
193
194.. code-block:: bash
195
196  (tutorial-env) $ pip install -r requirements.txt
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`
208guide for complete documentation for ``pip``.  When you've written
209a package and want to make it available on the Python Package Index,
210consult the :ref:`distributing-index` guide.
211