1515
1616--------------
1717
18+ .. _venv-def :
19+
1820The: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 _ andpip _ will install Python packages
32+ into the virtual environment's site directory without needing to be told to do
33+ so explicitly.
2434
2535See: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 assetuptools _ andpip _ 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
104137API
@@ -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 >`