Skip to content

Commit c11acb4

Browse files
pelsonpelson
committed
Doc: Refresh the venv introduction documentation, and correct the incorrect statement about the VIRTUAL_ENV environment variable
1 parent eae7dad commit c11acb4

File tree

2 files changed

+86
-95
lines changed

2 files changed

+86
-95
lines changed

‎Doc/library/venv.rst

+86-53
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,22 @@
1515

1616
--------------
1717

18+
.. _venv-def:
19+
1820
The :mod:`venv` module provides support for creating lightweight "virtual
19-
environments" with their own site directories, optionally isolated from system
20-
site directories. Each virtual environment has its own Python binary (which
21-
matches the version of the binary that was used to create this environment) and
22-
can have its own independent set of installed Python packages in its site
23-
directories.
21+
environments" with their own independent set of Python packages installed in
22+
their site directories. A virtual environment is created on top of an existing
23+
Python installation, known as the virtual environment's "base" Python, and may
24+
be optionally isolated from the base's site packages, meaning
25+
that packages installed in the base environment will not be accessible from
26+
the virtual environment.
27+
A virtual environment is therefore a powerful and convenient concept which
28+
allows quick, and relatively light-weight, Python environment creation.
29+
30+
When used from within a virtual environment, common installation tools such as
31+
setuptools_ and pip_ will install Python packages
32+
into the virtual environment's site directory without needing to be told to do
33+
so explicitly.
2434

2535
See :pep:`405` for more information about Python virtual environments.
2636

@@ -36,54 +46,66 @@ Creating virtual environments
3646

3747
.. include:: /using/venv-create.inc
3848

39-
40-
.. _venv-def:
41-
42-
.. note:: A virtual environment is a Python environment such that the Python
43-
interpreter, libraries and scripts installed into it are isolated from those
44-
installed in other virtual environments, and (by default) any libraries
45-
installed in a "system" Python, i.e., one which is installed as part of your
46-
operating system.
47-
48-
A virtual environment is a directory tree which contains Python executable
49-
files and other files which indicate that it is a virtual environment.
50-
51-
Common installation tools such as setuptools_ and pip_ work as
52-
expected with virtual environments. In other words, when a virtual
53-
environment is active, they install Python packages into the virtual
54-
environment without needing to be told to do so explicitly.
55-
56-
When a virtual environment is active (i.e., the virtual environment's Python
57-
interpreter is running), the attributes :attr:`sys.prefix` and
58-
:attr:`sys.exec_prefix` point to the base directory of the virtual
59-
environment, whereas :attr:`sys.base_prefix` and
60-
:attr:`sys.base_exec_prefix` point to the non-virtual environment Python
61-
installation which was used to create the virtual environment. If a virtual
62-
environment is not active, then :attr:`sys.prefix` is the same as
63-
:attr:`sys.base_prefix` and :attr:`sys.exec_prefix` is the same as
64-
:attr:`sys.base_exec_prefix` (they all point to a non-virtual environment
65-
Python installation).
66-
67-
When a virtual environment is active, any options that change the
68-
installation path will be ignored from all ``setuptools`` configuration
69-
files to prevent projects being inadvertently installed outside of the
70-
virtual environment.
71-
72-
When working in a command shell, users can make a virtual environment active
73-
by running an ``activate`` script in the virtual environment's executables
74-
directory (the precise filename and command to use the file is
75-
shell-dependent), which prepends the virtual environment's directory for
76-
executables to the ``PATH`` environment variable for the running shell. There
77-
should be no need in other circumstances to activate a virtual
78-
environment; scripts installed into virtual environments have a "shebang"
79-
line which points to the virtual environment's Python interpreter. This means
80-
that the script will run with that interpreter regardless of the value of
81-
``PATH``. On Windows, "shebang" line processing is supported if you have the
82-
Python Launcher for Windows installed (this was added to Python in 3.3 - see
83-
:pep:`397` for more details). Thus, double-clicking an installed script in a
84-
Windows Explorer window should run the script with the correct interpreter
85-
without there needing to be any reference to its virtual environment in
86-
``PATH``.
49+
Further venv detail
50+
-------------------
51+
52+
When a virtual environment is running, the attributes :attr:`sys.prefix` and
53+
:attr:`sys.exec_prefix` point to the prefix directory of the virtual
54+
environment, whereas :attr:`sys.base_prefix` and
55+
:attr:`sys.base_exec_prefix` point to the non-virtual environment Python
56+
installation which was used to create the virtual environment (known as the
57+
virtual environment's base environment). It is sufficient to check
58+
``sys.prefix == sys.base_prefix`` to determine if the current interpreter is
59+
a virtual environment.
60+
61+
A virtual environment may be "activated" using a script in the virtual
62+
environment's binary directory. This will prepend the virtual environment's
63+
binary directory to your path, so that running "python" will invoke the virtual
64+
environment's Python interpreter and you can run
65+
installed scripts without having to use their full path. The invocation of the
66+
activation script is platform-specific (`<venv>` must be replaced by the path of the
67+
directory containing the virtual environment):
68+
69+
+-------------+-----------------+-----------------------------------------+
70+
| Platform | Shell | Command to activate virtual environment |
71+
+=============+=================+=========================================+
72+
| POSIX | bash/zsh | $ source <venv>/bin/activate |
73+
+-------------+-----------------+-----------------------------------------+
74+
| | fish | $ source <venv>/bin/activate.fish |
75+
+-------------+-----------------+-----------------------------------------+
76+
| | csh/tcsh | $ source <venv>/bin/activate.csh |
77+
+-------------+-----------------+-----------------------------------------+
78+
| | PowerShell Core | $ <venv>/bin/Activate.ps1 |
79+
+-------------+-----------------+-----------------------------------------+
80+
| Windows | cmd.exe | C:\\> <venv>\\Scripts\\activate.bat |
81+
+-------------+-----------------+-----------------------------------------+
82+
| | PowerShell | PS C:\\> <venv>\\Scripts\\Activate.ps1 |
83+
+-------------+-----------------+-----------------------------------------+
84+
85+
.. versionadded:: 3.4
86+
``fish`` and ``csh`` activation scripts.
87+
88+
.. versionadded:: 3.8
89+
PowerShell activation scripts installed under POSIX for PowerShell Core
90+
support.
91+
92+
You don't specifically *need* to activate an environment, and all scripts
93+
installed in a virtual environment should be runnable without activating it.
94+
In order to achieve this, scripts installed into virtual environments have
95+
a "shebang" line which points to the virtual environment's Python interpreter.
96+
This means that the script will run with that interpreter regardless of the
97+
value of ``PATH``. On Windows, "shebang" line processing is supported if
98+
you have the Python Launcher for Windows installed (this was added to Python
99+
in 3.3 - see :pep:`397` for more details). Thus, double-clicking an installed
100+
script in a Windows Explorer window should run the script with the correct
101+
interpreter without there needing to be any reference to its virtual
102+
environment in :envvar:`PATH`.
103+
104+
When a virtual environment has been activated, the :envvar:`VIRTUAL_ENV`
105+
environment variable is set to the path of the virtual environment. Since it
106+
is not a requirement to explicitly activate a virtual environment in order
107+
to use it, the :envvar:`VIRTUAL_ENV` environment variable cannot be relied
108+
upon to determine whether a Python environment is virtual or not.
87109

88110
.. warning:: Because scripts installed in environments should not expect the
89111
environment to be activated, their shebang lines contain the absolute paths
@@ -99,6 +121,17 @@ Creating virtual environments
99121
environment in its new location. Otherwise, software installed into the
100122
environment may not work as expected.
101123

124+
You can deactivate a virtual environment by typing "deactivate" in your shell.
125+
The exact mechanism is platform-specific and is an internal implementation
126+
detail (typically a script or shell function will be used).
127+
128+
129+
.. note:: When a virtual environment is active, any options that change the
130+
installation path will be ignored from all :mod:`distutils` configuration
131+
files to prevent projects being inadvertently installed outside of the
132+
virtual environment.
133+
134+
102135
.. _venv-api:
103136

104137
API

‎Doc/using/venv-create.inc

-42
Original file line numberDiff line numberDiff line change
@@ -105,45 +105,3 @@ Multiple paths can be given to ``venv``, in which case an identical virtual
105105
environment will be created, according to the given options, at each provided
106106
path.
107107
108-
Once a virtual environment has been created, it can be "activated" using a
109-
script in the virtual environment's binary directory. The invocation of the
110-
script is platform-specific (`<venv>` must be replaced by the path of the
111-
directory containing the virtual environment):
112-
113-
+-------------+-----------------+-----------------------------------------+
114-
| Platform | Shell | Command to activate virtual environment |
115-
+=============+=================+=========================================+
116-
| POSIX | bash/zsh | $ source <venv>/bin/activate |
117-
+-------------+-----------------+-----------------------------------------+
118-
| | fish | $ source <venv>/bin/activate.fish |
119-
+-------------+-----------------+-----------------------------------------+
120-
| | csh/tcsh | $ source <venv>/bin/activate.csh |
121-
+-------------+-----------------+-----------------------------------------+
122-
| | PowerShell Core | $ <venv>/bin/Activate.ps1 |
123-
+-------------+-----------------+-----------------------------------------+
124-
| Windows | cmd.exe | C:\\> <venv>\\Scripts\\activate.bat |
125-
+-------------+-----------------+-----------------------------------------+
126-
| | PowerShell | PS C:\\> <venv>\\Scripts\\Activate.ps1 |
127-
+-------------+-----------------+-----------------------------------------+
128-
129-
When a virtual environment is active, the :envvar:`VIRTUAL_ENV` environment
130-
variable is set to the path of the virtual environment. This can be used to
131-
check if one is running inside a virtual environment.
132-
133-
You don't specifically *need* to activate an environment; activation just
134-
prepends the virtual environment's binary directory to your path, so that
135-
"python" invokes the virtual environment's Python interpreter and you can run
136-
installed scripts without having to use their full path. However, all scripts
137-
installed in a virtual environment should be runnable without activating it,
138-
and run with the virtual environment's Python automatically.
139-
140-
You can deactivate a virtual environment by typing "deactivate" in your shell.
141-
The exact mechanism is platform-specific and is an internal implementation
142-
detail (typically a script or shell function will be used).
143-
144-
.. versionadded:: 3.4
145-
``fish`` and ``csh`` activation scripts.
146-
147-
.. versionadded:: 3.8
148-
PowerShell activation scripts installed under POSIX for PowerShell Core
149-
support.

0 commit comments

Comments
 (0)