Skip to content

Commit 8c08a07

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 8c08a07

File tree

2 files changed

+86
-134
lines changed

2 files changed

+86
-134
lines changed

‎Doc/library/venv.rst

Lines changed: 86 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,32 @@
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.
34+
35+
When a virtual environment is active (i.e., the virtual environment's Python
36+
interpreter is running), the attributes :attr:`sys.prefix` and
37+
:attr:`sys.exec_prefix` point to the prefix directory of the virtual
38+
environment, whereas :attr:`sys.base_prefix` and
39+
:attr:`sys.base_exec_prefix` point to the non-virtual environment Python
40+
installation which was used to create the virtual environment (known as the
41+
virtual environment's base environment). It is sufficient to check
42+
``sys.prefix == sys.base_prefix`` to determine if the current interpreter is
43+
a virtual environment.
2444

2545
See :pep:`405` for more information about Python virtual environments.
2646

@@ -36,54 +56,56 @@ Creating virtual environments
3656

3757
.. include:: /using/venv-create.inc
3858

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``.
59+
Once a virtual environment has been created, it can be "activated" using a
60+
script in the virtual environment's binary directory. The invocation of the
61+
script is platform-specific (`<venv>` must be replaced by the path of the
62+
directory containing the virtual environment):
63+
64+
+-------------+-----------------+-----------------------------------------+
65+
| Platform | Shell | Command to activate virtual environment |
66+
+=============+=================+=========================================+
67+
| POSIX | bash/zsh | $ source <venv>/bin/activate |
68+
+-------------+-----------------+-----------------------------------------+
69+
| | fish | $ source <venv>/bin/activate.fish |
70+
+-------------+-----------------+-----------------------------------------+
71+
| | csh/tcsh | $ source <venv>/bin/activate.csh |
72+
+-------------+-----------------+-----------------------------------------+
73+
| | PowerShell Core | $ <venv>/bin/Activate.ps1 |
74+
+-------------+-----------------+-----------------------------------------+
75+
| Windows | cmd.exe | C:\\> <venv>\\Scripts\\activate.bat |
76+
+-------------+-----------------+-----------------------------------------+
77+
| | PowerShell | PS C:\\> <venv>\\Scripts\\Activate.ps1 |
78+
+-------------+-----------------+-----------------------------------------+
79+
80+
.. versionadded:: 3.4
81+
``fish`` and ``csh`` activation scripts.
82+
83+
.. versionadded:: 3.8
84+
PowerShell activation scripts installed under POSIX for PowerShell Core
85+
support.
86+
87+
You don't specifically *need* to activate an environment; activation just
88+
prepends the virtual environment's binary directory to your path, so that
89+
"python" invokes the virtual environment's Python interpreter and you can run
90+
installed scripts without having to use their full path. However, all scripts
91+
installed in a virtual environment should be runnable without activating it,
92+
and run with the virtual environment's Python automatically.
93+
94+
Scripts installed into virtual environments have a "shebang" line which points
95+
to the virtual environment's Python interpreter. This means that the script
96+
will run with that interpreter regardless of the value of ``PATH``.
97+
On Windows, "shebang" line processing is supported if you have the
98+
Python Launcher for Windows installed (this was added to Python in 3.3 - see
99+
:pep:`397` for more details). Thus, double-clicking an installed script in a
100+
Windows Explorer window should run the script with the correct interpreter
101+
without there needing to be any reference to its virtual environment in
102+
: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
@@ -191,45 +224,6 @@ creation according to their needs, the :class:`EnvBuilder` class.
191224
``clear=True``, contents of the environment directory will be cleared
192225
and then all necessary subdirectories will be recreated.
193226

194-
The returned context object is a :class:`types.SimpleNamespace` with the
195-
following attributes:
196-
197-
* ``env_dir`` - The location of the virtual environment. Used for
198-
``__VENV_DIR__`` in activation scripts (see :meth:`install_scripts`).
199-
200-
* ``env_name`` - The name of the virtual environment. Used for
201-
``__VENV_NAME__`` in activation scripts (see :meth:`install_scripts`).
202-
203-
* ``prompt`` - The prompt to be used by the activation scripts. Used for
204-
``__VENV_PROMPT__`` in activation scripts (see :meth:`install_scripts`).
205-
206-
* ``executable`` - The underlying Python executable used by the virtual
207-
environment. This takes into account the case where a virtual environment
208-
is created from another virtual environment.
209-
210-
* ``inc_path`` - The include path for the virtual environment.
211-
212-
* ``lib_path`` - The purelib path for the virtual environment.
213-
214-
* ``bin_path`` - The script path for the virtual environment.
215-
216-
* ``bin_name`` - The name of the script path relative to the virtual
217-
environment location. Used for ``__VENV_BIN_NAME__`` in activation
218-
scripts (see :meth:`install_scripts`).
219-
220-
* ``env_exe`` - The name of the Python interpreter in the virtual
221-
environment. Used for ``__VENV_PYTHON__`` in activation scripts
222-
(see :meth:`install_scripts`).
223-
224-
* ``env_exec_cmd`` - The name of the Python interpreter, taking into
225-
account filesystem redirections. This can be used to run Python in
226-
the virtual environment.
227-
228-
229-
.. versionchanged:: 3.12
230-
The attribute ``lib_path`` was added to the context, and the context
231-
object was documented.
232-
233227
.. versionchanged:: 3.11
234228
The *venv*
235229
:ref:`sysconfig installation scheme <installation_paths>`

‎Doc/using/venv-create.inc

Lines changed: 0 additions & 42 deletions
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)