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 moreinformation about Python virtual environments.
33+ See:pep: `405 ` for morebackground 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 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: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> }
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
104135API
@@ -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 >`