Skip to content

Commit b02b210

Browse files
pelsonCAM-Gerlach
authored and
vsajip
committed
[doc] Refresh the venv introduction documentation, and correct the statement about VIRTUAL_ENV (pythonGH-98350)
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> (cherry picked from commit 1a6bacb)
1 parent f0c0d30 commit b02b210

File tree

2 files changed

+123
-95
lines changed

2 files changed

+123
-95
lines changed

‎Doc/library/venv.rst

+123-53
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,22 @@
1515

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

18-
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.
18+
.. _venv-def:
19+
.. _venv-intro:
20+
21+
The :mod:`!venv` module supports creating lightweight "virtual environments",
22+
each with their own independent set of Python packages installed in
23+
their :mod:`site` directories.
24+
A virtual environment is created on top of an existing
25+
Python installation, known as the virtual environment's "base" Python, and may
26+
optionally be isolated from the packages in the base environment,
27+
so only those explicitly installed in the virtual environment are available.
28+
29+
When used from within a virtual environment, common installation tools such as
30+
`pip`_ will install Python packages into a virtual environment
31+
without needing to be told to do so explicitly.
2432

25-
See :pep:`405` for more information about Python virtual environments.
33+
See :pep:`405` for more background on Python virtual environments.
2634

2735
.. seealso::
2836

@@ -36,54 +44,72 @@ Creating virtual environments
3644

3745
.. include:: /using/venv-create.inc
3846

47+
.. _venv-explanation:
3948

40-
.. _venv-def:
49+
How venvs work
50+
--------------
4151

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 :mod:`distutils` 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``.
52+
When a Python interpreter is running from a virtual environment,
53+
:data:`sys.prefix` and :data:`sys.exec_prefix`
54+
point to the directories of the virtual environment,
55+
whereas :data:`sys.base_prefix` and :data:`sys.base_exec_prefix`
56+
point to those of the base Python used to create the environment.
57+
It is sufficient to check
58+
``sys.prefix == sys.base_prefix`` to determine if the current interpreter is
59+
running from a virtual environment.
60+
61+
A virtual environment may be "activated" using a script in its binary directory
62+
(``bin`` on POSIX; ``Scripts`` on Windows).
63+
This will prepend that directory to your :envvar:`!PATH`, so that running
64+
:program:`!python` will invoke the environment's Python interpreter
65+
and you can run installed scripts without having to use their full path.
66+
The invocation of the activation script is platform-specific
67+
(:samp:`{<venv>}` must be replaced by the path to the directory
68+
containing the virtual environment):
69+
70+
+-------------+------------+--------------------------------------------------+
71+
| Platform | Shell | Command to activate virtual environment |
72+
+=============+============+==================================================+
73+
| POSIX | bash/zsh | :samp:`$ source {<venv>}/bin/activate` |
74+
| +------------+--------------------------------------------------+
75+
| | fish | :samp:`$ source {<venv>}/bin/activate.fish` |
76+
| +------------+--------------------------------------------------+
77+
| | csh/tcsh | :samp:`$ source {<venv>}/bin/activate.csh` |
78+
| +------------+--------------------------------------------------+
79+
| | PowerShell | :samp:`$ {<venv>}/bin/Activate.ps1` |
80+
+-------------+------------+--------------------------------------------------+
81+
| Windows | cmd.exe | :samp:`C:\\> {<venv>}\\Scripts\\activate.bat` |
82+
| +------------+--------------------------------------------------+
83+
| | PowerShell | :samp:`PS C:\\> {<venv>}\\Scripts\\Activate.ps1` |
84+
+-------------+------------+--------------------------------------------------+
85+
86+
.. versionadded:: 3.4
87+
:program:`!fish` and :program:`!csh` activation scripts.
88+
89+
.. versionadded:: 3.8
90+
PowerShell activation scripts installed under POSIX for PowerShell Core
91+
support.
92+
93+
You don't specifically *need* to activate a virtual environment,
94+
as you can just specify the full path to that environment's
95+
Python interpreter when invoking Python.
96+
Furthermore, all scripts installed in the environment
97+
should be runnable without activating it.
98+
99+
In order to achieve this, scripts installed into virtual environments have
100+
a "shebang" line which points to the environment's Python interpreter,
101+
i.e. :samp:`#!/{<path-to-venv>}/bin/python`.
102+
This means that the script will run with that interpreter regardless of the
103+
value of :envvar:`!PATH`. On Windows, "shebang" line processing is supported if
104+
you have the :ref:`launcher` installed. Thus, double-clicking an installed
105+
script in a Windows Explorer window should run it with the correct interpreter
106+
without the environment needing to be activated or on the :envvar:`!PATH`.
107+
108+
When a virtual environment has been activated, the :envvar:`!VIRTUAL_ENV`
109+
environment variable is set to the path of the environment.
110+
Since explicitly activating a virtual environment is not required to use it,
111+
:envvar:`!VIRTUAL_ENV` cannot be relied upon to determine
112+
whether a virtual environment is being used.
87113

88114
.. warning:: Because scripts installed in environments should not expect the
89115
environment to be activated, their shebang lines contain the absolute paths
@@ -99,6 +125,11 @@ Creating virtual environments
99125
environment in its new location. Otherwise, software installed into the
100126
environment may not work as expected.
101127

128+
You can deactivate a virtual environment by typing ``deactivate`` in your shell.
129+
The exact mechanism is platform-specific and is an internal implementation
130+
detail (typically, a script or shell function will be used).
131+
132+
102133
.. _venv-api:
103134

104135
API
@@ -191,6 +222,45 @@ creation according to their needs, the :class:`EnvBuilder` class.
191222
``clear=True``, contents of the environment directory will be cleared
192223
and then all necessary subdirectories will be recreated.
193224

225+
The returned context object is a :class:`types.SimpleNamespace` with the
226+
following attributes:
227+
228+
* ``env_dir`` - The location of the virtual environment. Used for
229+
``__VENV_DIR__`` in activation scripts (see :meth:`install_scripts`).
230+
231+
* ``env_name`` - The name of the virtual environment. Used for
232+
``__VENV_NAME__`` in activation scripts (see :meth:`install_scripts`).
233+
234+
* ``prompt`` - The prompt to be used by the activation scripts. Used for
235+
``__VENV_PROMPT__`` in activation scripts (see :meth:`install_scripts`).
236+
237+
* ``executable`` - The underlying Python executable used by the virtual
238+
environment. This takes into account the case where a virtual environment
239+
is created from another virtual environment.
240+
241+
* ``inc_path`` - The include path for the virtual environment.
242+
243+
* ``lib_path`` - The purelib path for the virtual environment.
244+
245+
* ``bin_path`` - The script path for the virtual environment.
246+
247+
* ``bin_name`` - The name of the script path relative to the virtual
248+
environment location. Used for ``__VENV_BIN_NAME__`` in activation
249+
scripts (see :meth:`install_scripts`).
250+
251+
* ``env_exe`` - The name of the Python interpreter in the virtual
252+
environment. Used for ``__VENV_PYTHON__`` in activation scripts
253+
(see :meth:`install_scripts`).
254+
255+
* ``env_exec_cmd`` - The name of the Python interpreter, taking into
256+
account filesystem redirections. This can be used to run Python in
257+
the virtual environment.
258+
259+
260+
.. versionchanged:: 3.12
261+
The attribute ``lib_path`` was added to the context, and the context
262+
object was documented.
263+
194264
.. versionchanged:: 3.11
195265
The *venv*
196266
:ref:`sysconfig installation scheme <installation_paths>`

‎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)