Debian Codegraph @

Doc/tutorial/venv.rst

raw
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
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.
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
30 installed while application B has another virtual environment with version 2.0.
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
38 The module used to create and manage virtual environments is called
39 :mod:`venv`. :mod:`venv` will install the Python version from which
40 the command was run (as reported by the :option:`--version` option).
41 For instance, executing the command with ``python3.12`` will install
42 version 3.12.
43
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::
46
47 python -m venv tutorial-env
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
51 interpreter and various supporting files.
52
53 A common directory location for a virtual environment is ``.venv``.
54 This name keeps the directory typically hidden in your shell and thus
55 out of the way while giving it a name that explains why the directory
56 exists. It also prevents clashing with ``.env`` environment variable
57 definition files that some tooling supports.
58
59 Once you've created a virtual environment, you may activate it.
60
61 On Windows, run::
62
63 tutorial-env\Scripts\activate
64
65 On 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
72 instead.)
73
74 Activating the virtual environment will change your shell's prompt to show what
75 virtual environment you're using, and modify the environment so that running
76 ``python`` will get you that particular version and installation of Python.
77 For 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 Note that the activated virtual environment does not alter the ``PYTHONPATH`` variable in any way.
92 This may lead to unexpected results if the path includes references to code which is incompatible with
93 the Python version the virtual environment is using. The best practice is to ``unset PYTHONPATH``
94 in bash or the equivalent for the shell you are using.
95
96 To deactivate a virtual environment, type::
97
98 deactivate
99
100 into the terminal.
101
102 Managing Packages with pip
103 ==========================
104
105 You can install, upgrade, and remove packages using a program called
106 :program:`pip`. By default ``pip`` will install packages from the `Python
107 Package Index <https://pypi.org>`_. You can browse the Python
108 Package Index by going to it in your web browser.
109
110 ``pip`` has a number of subcommands: "install", "uninstall",
111 "freeze", etc. (Consult the :ref:`installing-index` guide for
112 complete documentation for ``pip``.)
113
114 You can install the latest version of a package by specifying a package's name:
115
116 .. code-block:: bash
117
118 (tutorial-env) $ python -m pip install novas
119 Collecting novas
120 Downloading novas-3.1.1.3.tar.gz (136kB)
121 Installing collected packages: novas
122 Running setup.py install for novas
123 Successfully installed novas-3.1.1.3
124
125 You can also install a specific version of a package by giving the
126 package name followed by ``==`` and the version number:
127
128 .. code-block:: bash
129
130 (tutorial-env) $ python -m pip install requests==2.6.0
131 Collecting requests==2.6.0
132 Using cached requests-2.6.0-py2.py3-none-any.whl
133 Installing collected packages: requests
134 Successfully installed requests-2.6.0
135
136 If you re-run this command, ``pip`` will notice that the requested
137 version is already installed and do nothing. You can supply a
138 different version number to get that version, or you can run ``python
139 -m pip install --upgrade`` to upgrade the package to the latest version:
140
141 .. code-block:: bash
142
143 (tutorial-env) $ python -m pip install --upgrade requests
144 Collecting requests
145 Installing collected packages: requests
146 Found existing installation: requests 2.6.0
147 Uninstalling requests-2.6.0:
148 Successfully uninstalled requests-2.6.0
149 Successfully installed requests-2.7.0
150
151 ``python -m pip uninstall`` followed by one or more package names will
152 remove the packages from the virtual environment.
153
154 ``python -m pip show`` will display information about a particular package:
155
156 .. code-block:: bash
157
158 (tutorial-env) $ python -m pip show requests
159 ---
160 Metadata-Version: 2.0
161 Name: requests
162 Version: 2.7.0
163 Summary: Python HTTP for Humans.
164 Home-page: http://python-requests.org
165 Author: Kenneth Reitz
166 Author-email: [email protected]
167 License: Apache 2.0
168 Location: /Users/akuchling/envs/tutorial-env/lib/python3.4/site-packages
169 Requires:
170
171 ``python -m pip list`` will display all of the packages installed in
172 the virtual environment:
173
174 .. code-block:: bash
175
176 (tutorial-env) $ python -m pip list
177 novas (3.1.1.3)
178 numpy (1.9.2)
179 pip (7.0.3)
180 requests (2.7.0)
181 setuptools (16.0)
182
183 ``python -m pip freeze`` will produce a similar list of the installed packages,
184 but the output uses the format that ``python -m pip install`` expects.
185 A common convention is to put this list in a ``requirements.txt`` file:
186
187 .. code-block:: bash
188
189 (tutorial-env) $ python -m pip freeze > requirements.txt
190 (tutorial-env) $ cat requirements.txt
191 novas==3.1.1.3
192 numpy==1.9.2
193 requests==2.7.0
194
195 The ``requirements.txt`` can then be committed to version control and
196 shipped as part of an application. Users can then install all the
197 necessary packages with ``install -r``:
198
199 .. code-block:: bash
200
201 (tutorial-env) $ python -m pip install -r requirements.txt
202 Collecting novas==3.1.1.3 (from -r requirements.txt (line 1))
203 ...
204 Collecting numpy==1.9.2 (from -r requirements.txt (line 2))
205 ...
206 Collecting requests==2.7.0 (from -r requirements.txt (line 3))
207 ...
208 Installing collected packages: novas, numpy, requests
209 Running setup.py install for novas
210 Successfully installed novas-3.1.1.3 numpy-1.9.2 requests-2.7.0
211
212 ``pip`` has many more options. Consult the :ref:`installing-index`
213 guide for complete documentation for ``pip``. When you've written
214 a package and want to make it available on the Python Package Index,
215 consult the `Python packaging user guide`_.
216
217 .. _Python Packaging User Guide: https://packaging.python.org/en/latest/tutorials/packaging-projects/