-
Notifications
You must be signed in to change notification settings - Fork 3
/
venv.html
416 lines (416 loc) · 14.7 KB
/
venv.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta
name="viewport"
content="width=device-width, initial-scale=1.0, user-scalable=yes"
/>
<title>venv</title>
<style type="text/css">
code {
white-space: pre-wrap;
}
span.smallcaps {
font-variant: small-caps;
}
span.underline {
text-decoration: underline;
}
div.column {
display: inline-block;
vertical-align: top;
width: 50%;
}
</style>
</head>
<body>
<h3 id="navigation">Navigation</h3>
<ul>
<li>
<a href="https://docs.python.org/3/genindex.html" title="General Index"
>index</a
>
</li>
<li>
<a
href="https://docs.python.org/3/py-modindex.html"
title="Python Module Index"
>modules</a
>
|
</li>
<li><a href="whatnow.html" title="13. What Now?">next</a> |</li>
<li>
<a
href="stdlib2.html"
title="11. Brief Tour of the Standard Library — Part II"
>previous</a
>
|
</li>
<li><img src="../_static/py.png" /></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="https://docs.python.org/3/index.html">3.9.5 Documentation</a> »
</li>
<li><a href="index.html">The Python Tutorial</a> »</li>
<li></li>
</ul>
<p><span id="tut-venv"></span></p>
<h1 id="virtual-environments-and-packages">
<span class="section-number">12. </span>Virtual Environments and
Packages<a
href="#virtual-environments-and-packages"
class="headerlink"
title="Permalink to this headline"
>¶</a
>
</h1>
<h2 id="introduction">
<span class="section-number">12.1. </span>Introduction<a
href="#introduction"
class="headerlink"
title="Permalink to this headline"
>¶</a
>
</h2>
<p>
Python applications will often use packages and modules that don’t come as
part of the standard library. Applications will sometimes need a specific
version of a library, because the application may require that a
particular bug has been fixed or the application may be written using an
obsolete version of the library’s interface.
</p>
<p>
This means it may not be possible for one Python installation to meet the
requirements of every application. If application A needs version 1.0 of a
particular module but application B needs version 2.0, then the
requirements are in conflict and installing either version 1.0 or 2.0 will
leave one application unable to run.
</p>
<p>
The solution for this problem is to create a
<a
href="https://docs.python.org/3/glossary.html#term-virtual-environment"
class="reference internal"
><span class="xref std std-term">virtual environment</span></a
>, a self-contained directory tree that contains a Python installation for
a particular version of Python, plus a number of additional packages.
</p>
<p>
Different applications can then use different virtual environments. To
resolve the earlier example of conflicting requirements, application A can
have its own virtual environment with version 1.0 installed while
application B has another virtual environment with version 2.0. If
application B requires a library be upgraded to version 3.0, this will not
affect application A’s environment.
</p>
<h2 id="creating-virtual-environments">
<span class="section-number">12.2. </span>Creating Virtual Environments<a
href="#creating-virtual-environments"
class="headerlink"
title="Permalink to this headline"
>¶</a
>
</h2>
<p>
The module used to create and manage virtual environments is called
<a
href="https://docs.python.org/3/library/venv.html#module-venv"
class="reference internal"
title="venv: Creation of virtual environments."
><code class="sourceCode python">venv</code></a
>.
<a
href="https://docs.python.org/3/library/venv.html#module-venv"
class="reference internal"
title="venv: Creation of virtual environments."
><code class="sourceCode python">venv</code></a
>
will usually install the most recent version of Python that you have
available. If you have multiple versions of Python on your system, you can
select a specific Python version by running <code>python3</code> or
whichever version you want.
</p>
<p>
To create a virtual environment, decide upon a directory where you want to
place it, and run the
<a
href="https://docs.python.org/3/library/venv.html#module-venv"
class="reference internal"
title="venv: Creation of virtual environments."
><code class="sourceCode python">venv</code></a
>
module as a script with the directory path:
</p>
<pre><code>python3 -m venv tutorial-env</code></pre>
<p>
This will create the <code>tutorial-env</code> directory if it doesn’t
exist, and also create directories inside it containing a copy of the
Python interpreter, the standard library, and various supporting files.
</p>
<p>
A common directory location for a virtual environment is
<code>.venv</code>. This name keeps the directory typically hidden in your
shell and thus out of the way while giving it a name that explains why the
directory exists. It also prevents clashing with
<code>.env</code> environment variable definition files that some tooling
supports.
</p>
<p>Once you’ve created a virtual environment, you may activate it.</p>
<p>On Windows, run:</p>
<pre><code>tutorial-env\Scripts\activate.bat</code></pre>
<p>On Unix or MacOS, run:</p>
<pre><code>source tutorial-env/bin/activate</code></pre>
<p>
(This script is written for the bash shell. If you use the
<strong>csh</strong> or <strong>fish</strong> shells, there are alternate
<code>activate.csh</code> and <code>activate.fish</code> scripts you
should use instead.)
</p>
<p>
Activating the virtual environment will change your shell’s prompt to show
what virtual environment you’re using, and modify the environment so that
running <code>python</code> will get you that particular version and
installation of Python. For example:
</p>
<pre><code>$ source ~/envs/tutorial-env/bin/activate
(tutorial-env) $ python
Python 3.5.1 (default, May 6 2016, 10:59:36)
...
>>> import sys
>>> sys.path
['', '/usr/local/lib/python35.zip', ...,
'~/envs/tutorial-env/lib/python3.5/site-packages']
>>></code></pre>
<h2 id="managing-packages-with-pip">
<span class="section-number">12.3. </span>Managing Packages with pip<a
href="#managing-packages-with-pip"
class="headerlink"
title="Permalink to this headline"
>¶</a
>
</h2>
<p>
You can install, upgrade, and remove packages using a program called
<strong>pip</strong>. By default <code>pip</code> will install packages
from the Python Package Index, <<a
href="https://pypi.org/"
class="reference external"
>https://pypi.org</a
>>. You can browse the Python Package Index by going to it in your web
browser.
</p>
<p>
<code>pip</code> has a number of subcommands: “install”, “uninstall”,
“freeze”, etc. (Consult the
<a
href="https://docs.python.org/3/installing/index.html#installing-index"
class="reference internal"
><span class="std std-ref">Installing Python Modules</span></a
>
guide for complete documentation for <code>pip</code>.)
</p>
<p>
You can install the latest version of a package by specifying a package’s
name:
</p>
<pre><code>(tutorial-env) $ python -m pip install novas
Collecting novas
Downloading novas-3.1.1.3.tar.gz (136kB)
Installing collected packages: novas
Running setup.py install for novas
Successfully installed novas-3.1.1.3</code></pre>
<p>
You can also install a specific version of a package by giving the package
name followed by <code>==</code> and the version number:
</p>
<pre><code>(tutorial-env) $ python -m pip install requests==2.6.0
Collecting requests==2.6.0
Using cached requests-2.6.0-py2.py3-none-any.whl
Installing collected packages: requests
Successfully installed requests-2.6.0</code></pre>
<p>
If you re-run this command, <code>pip</code> will notice that the
requested version is already installed and do nothing. You can supply a
different version number to get that version, or you can run
<code>pip install --upgrade</code> to upgrade the package to the latest
version:
</p>
<pre><code>(tutorial-env) $ python -m pip install --upgrade requests
Collecting requests
Installing collected packages: requests
Found existing installation: requests 2.6.0
Uninstalling requests-2.6.0:
Successfully uninstalled requests-2.6.0
Successfully installed requests-2.7.0</code></pre>
<p>
<code>pip uninstall</code> followed by one or more package names will
remove the packages from the virtual environment.
</p>
<p>
<code>pip show</code> will display information about a particular package:
</p>
<pre><code>(tutorial-env) $ pip show requests
---
Metadata-Version: 2.0
Name: requests
Version: 2.7.0
Summary: Python HTTP for Humans.
Home-page: http://python-requests.org
Author: Kenneth Reitz
Author-email: [email protected]
License: Apache 2.0
Location: /Users/akuchling/envs/tutorial-env/lib/python3.4/site-packages
Requires:</code></pre>
<p>
<code>pip list</code> will display all of the packages installed in the
virtual environment:
</p>
<pre><code>(tutorial-env) $ pip list
novas (3.1.1.3)
numpy (1.9.2)
pip (7.0.3)
requests (2.7.0)
setuptools (16.0)</code></pre>
<p>
<code>pip freeze</code> will produce a similar list of the installed
packages, but the output uses the format that
<code>pip install</code> expects. A common convention is to put this list
in a <code>requirements.txt</code> file:
</p>
<pre><code>(tutorial-env) $ pip freeze > requirements.txt
(tutorial-env) $ cat requirements.txt
novas==3.1.1.3
numpy==1.9.2
requests==2.7.0</code></pre>
<p>
The <code>requirements.txt</code> can then be committed to version control
and shipped as part of an application. Users can then install all the
necessary packages with <code>install -r</code>:
</p>
<pre><code>(tutorial-env) $ python -m pip install -r requirements.txt
Collecting novas==3.1.1.3 (from -r requirements.txt (line 1))
...
Collecting numpy==1.9.2 (from -r requirements.txt (line 2))
...
Collecting requests==2.7.0 (from -r requirements.txt (line 3))
...
Installing collected packages: novas, numpy, requests
Running setup.py install for novas
Successfully installed novas-3.1.1.3 numpy-1.9.2 requests-2.7.0</code></pre>
<p>
<code>pip</code> has many more options. Consult the
<a
href="https://docs.python.org/3/installing/index.html#installing-index"
class="reference internal"
><span class="std std-ref">Installing Python Modules</span></a
>
guide for complete documentation for <code>pip</code>. When you’ve written
a package and want to make it available on the Python Package Index,
consult the
<a
href="https://docs.python.org/3/distributing/index.html#distributing-index"
class="reference internal"
><span class="std std-ref">Distributing Python Modules</span></a
>
guide.
</p>
<h3 id="table-of-contents">
<a href="https://docs.python.org/3/contents.html">Table of Contents</a>
</h3>
<ul>
<li>
<a href="#" class="reference internal"
>12. Virtual Environments and Packages</a
>
<ul>
<li>
<a href="#introduction" class="reference internal"
>12.1. Introduction</a
>
</li>
<li>
<a href="#creating-virtual-environments" class="reference internal"
>12.2. Creating Virtual Environments</a
>
</li>
<li>
<a href="#managing-packages-with-pip" class="reference internal"
>12.3. Managing Packages with pip</a
>
</li>
</ul>
</li>
</ul>
<h4 id="previous-topic">Previous topic</h4>
<p>
<a href="stdlib2.html" title="previous chapter"
><span class="section-number">11. </span>Brief Tour of the Standard
Library — Part II</a
>
</p>
<h4 id="next-topic">Next topic</h4>
<p>
<a href="whatnow.html" title="next chapter"
><span class="section-number">13. </span>What Now?</a
>
</p>
<h3 id="this-page">This Page</h3>
<ul>
<li><a href="https://docs.python.org/3/bugs.html">Report a Bug</a></li>
<li>
<a
href="https://github.com/python/cpython/blob/3.9/Doc/tutorial/venv.rst"
>Show Source</a
>
</li>
</ul>
<h3 id="navigation-1">Navigation</h3>
<ul>
<li>
<a href="https://docs.python.org/3/genindex.html" title="General Index"
>index</a
>
</li>
<li>
<a
href="https://docs.python.org/3/py-modindex.html"
title="Python Module Index"
>modules</a
>
|
</li>
<li><a href="whatnow.html" title="13. What Now?">next</a> |</li>
<li>
<a
href="stdlib2.html"
title="11. Brief Tour of the Standard Library — Part II"
>previous</a
>
|
</li>
<li><img src="../_static/py.png" /></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="https://docs.python.org/3/index.html">3.9.5 Documentation</a> »
</li>
<li><a href="index.html">The Python Tutorial</a> »</li>
<li></li>
</ul>
<p>
©
<a href="https://docs.python.org/3/copyright.html">Copyright</a>
2001-2021, Python Software Foundation.<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
</p>
<p>
Last updated on May 30, 2021.
<a href="https://docs.python.org/3/bugs.html">Found a bug</a>?<br />
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 2.4.4.
</p>
</body>
</html>