|
Expand Up
|
@@ -15,14 +15,22 @@ |
|
|
|
|
|
-------------- |
|
|
|
|
|
The :mod:`venv` module provides support for creating lightweight "virtual |
|
|
environments" with their own site directories, optionally isolated from system |
|
|
site directories. Each virtual environment has its own Python binary (which |
|
|
matches the version of the binary that was used to create this environment) and |
|
|
can have its own independent set of installed Python packages in its site |
|
|
directories. |
|
|
.. _venv-def: |
Comment thread
pelson marked this conversation as resolved.
Resolved
Uh oh!
There was an error while loading. Please reload this page.
|
|
|
.. _venv-intro: |
|
|
|
|
|
The :mod:`!venv` module supports creating lightweight "virtual environments", |
|
|
each with their own independent set of Python packages installed in |
|
|
their :mod:`site` directories. |
|
|
A virtual environment is created on top of an existing |
|
|
Python installation, known as the virtual environment's "base" Python, and may |
|
|
optionally be isolated from the packages in the base environment, |
|
|
so only those explicitly installed in the virtual environment are available. |
|
|
|
|
|
See :pep:`405` for more information about Python virtual environments. |
|
|
When used from within a virtual environment, common installation tools such as |
|
|
`pip`_ will install Python packages into a virtual environment |
|
|
without needing to be told to do so explicitly. |
|
|
|
|
|
See :pep:`405` for more background on Python virtual environments. |
|
|
|
|
|
.. seealso:: |
|
|
|
|
Expand All
|
@@ -36,54 +44,72 @@ Creating virtual environments |
|
|
|
|
|
.. include:: /using/venv-create.inc |
|
|
|
|
|
.. _venv-explanation: |
|
|
|
|
|
.. _venv-def: |
|
|
How venvs work |
|
|
-------------- |
|
|
|
|
|
.. note:: A virtual environment is a Python environment such that the Python |
|
|
interpreter, libraries and scripts installed into it are isolated from those |
|
|
installed in other virtual environments, and (by default) any libraries |
|
|
installed in a "system" Python, i.e., one which is installed as part of your |
|
|
operating system. |
|
|
|
|
|
A virtual environment is a directory tree which contains Python executable |
|
|
files and other files which indicate that it is a virtual environment. |
|
|
|
|
|
Common installation tools such as setuptools_ and pip_ work as |
|
|
expected with virtual environments. In other words, when a virtual |
|
|
environment is active, they install Python packages into the virtual |
|
|
environment without needing to be told to do so explicitly. |
|
|
|
|
|
When a virtual environment is active (i.e., the virtual environment's Python |
|
|
interpreter is running), the attributes :attr:`sys.prefix` and |
|
|
:attr:`sys.exec_prefix` point to the base directory of the virtual |
|
|
environment, whereas :attr:`sys.base_prefix` and |
|
|
:attr:`sys.base_exec_prefix` point to the non-virtual environment Python |
|
|
installation which was used to create the virtual environment. If a virtual |
|
|
environment is not active, then :attr:`sys.prefix` is the same as |
|
|
:attr:`sys.base_prefix` and :attr:`sys.exec_prefix` is the same as |
|
|
:attr:`sys.base_exec_prefix` (they all point to a non-virtual environment |
|
|
Python installation). |
|
|
|
|
|
When a virtual environment is active, any options that change the |
|
|
installation path will be ignored from all ``setuptools`` configuration |
|
|
files to prevent projects being inadvertently installed outside of the |
|
|
virtual environment. |
|
|
|
|
|
When working in a command shell, users can make a virtual environment active |
|
|
by running an ``activate`` script in the virtual environment's executables |
|
|
directory (the precise filename and command to use the file is |
|
|
shell-dependent), which prepends the virtual environment's directory for |
|
|
executables to the ``PATH`` environment variable for the running shell. There |
|
|
should be no need in other circumstances to activate a virtual |
|
|
environment; scripts installed into virtual environments have a "shebang" |
|
|
line which points to the virtual environment's Python interpreter. This means |
|
|
that the script will run with that interpreter regardless of the value of |
|
|
``PATH``. On Windows, "shebang" line processing is supported if you have the |
|
|
Python Launcher for Windows installed (this was added to Python in 3.3 - see |
|
|
:pep:`397` for more details). Thus, double-clicking an installed script in a |
|
|
Windows Explorer window should run the script with the correct interpreter |
|
|
without there needing to be any reference to its virtual environment in |
|
|
``PATH``. |
|
|
When a Python interpreter is running from a virtual environment, |
|
|
:data:`sys.prefix` and :data:`sys.exec_prefix` |
|
|
point to the directories of the virtual environment, |
|
|
whereas :data:`sys.base_prefix` and :data:`sys.base_exec_prefix` |
|
|
point to those of the base Python used to create the environment. |
|
|
It is sufficient to check |
|
|
``sys.prefix == sys.base_prefix`` to determine if the current interpreter is |
|
|
running from a virtual environment. |
|
|
|
|
|
A virtual environment may be "activated" using a script in its binary directory |
|
|
(``bin`` on POSIX; ``Scripts`` on Windows). |
|
|
This will prepend that directory to your :envvar:`!PATH`, so that running |
|
|
:program:`!python` will invoke the environment's Python interpreter |
|
|
and you can run installed scripts without having to use their full path. |
|
|
The invocation of the activation script is platform-specific |
|
|
(:samp:`{<venv>}` must be replaced by the path to the directory |
|
|
containing the virtual environment): |
|
|
|
|
|
+-------------+------------+--------------------------------------------------+ |
|
|
| Platform | Shell | Command to activate virtual environment | |
|
|
+=============+============+==================================================+ |
|
|
| POSIX | bash/zsh | :samp:`$ source {<venv>}/bin/activate` | |
|
|
| +------------+--------------------------------------------------+ |
|
|
| | fish | :samp:`$ source {<venv>}/bin/activate.fish` | |
|
|
| +------------+--------------------------------------------------+ |
|
|
| | csh/tcsh | :samp:`$ source {<venv>}/bin/activate.csh` | |
|
|
| +------------+--------------------------------------------------+ |
|
|
| | PowerShell | :samp:`$ {<venv>}/bin/Activate.ps1` | |
|
|
+-------------+------------+--------------------------------------------------+ |
|
|
| Windows | cmd.exe | :samp:`C:\\> {<venv>}\\Scripts\\activate.bat` | |
|
|
| +------------+--------------------------------------------------+ |
|
|
| | PowerShell | :samp:`PS C:\\> {<venv>}\\Scripts\\Activate.ps1` | |
|
|
+-------------+------------+--------------------------------------------------+ |
|
|
|
|
|
.. versionadded:: 3.4 |
|
|
:program:`!fish` and :program:`!csh` activation scripts. |
|
|
|
|
|
.. versionadded:: 3.8 |
|
|
PowerShell activation scripts installed under POSIX for PowerShell Core |
|
|
support. |
|
|
|
|
|
You don't specifically *need* to activate a virtual environment, |
|
|
as you can just specify the full path to that environment's |
|
|
Python interpreter when invoking Python. |
|
|
Furthermore, all scripts installed in the environment |
|
|
should be runnable without activating it. |
|
|
|
|
|
In order to achieve this, scripts installed into virtual environments have |
|
|
a "shebang" line which points to the environment's Python interpreter, |
|
|
i.e. :samp:`#!/{<path-to-venv>}/bin/python`. |
|
|
This means that the script will run with that interpreter regardless of the |
|
|
value of :envvar:`!PATH`. On Windows, "shebang" line processing is supported if |
|
|
you have the :ref:`launcher` installed. Thus, double-clicking an installed |
|
|
script in a Windows Explorer window should run it with the correct interpreter |
|
|
without the environment needing to be activated or on the :envvar:`!PATH`. |
|
|
|
|
|
When a virtual environment has been activated, the :envvar:`!VIRTUAL_ENV` |
|
|
environment variable is set to the path of the environment. |
|
|
Since explicitly activating a virtual environment is not required to use it, |
|
|
:envvar:`!VIRTUAL_ENV` cannot be relied upon to determine |
|
|
whether a virtual environment is being used. |
|
|
|
|
|
.. warning:: Because scripts installed in environments should not expect the |
|
|
environment to be activated, their shebang lines contain the absolute paths |
|
Expand All
|
@@ -99,6 +125,11 @@ Creating virtual environments |
|
|
environment in its new location. Otherwise, software installed into the |
|
|
environment may not work as expected. |
|
|
|
|
|
You can deactivate a virtual environment by typing ``deactivate`` in your shell. |
|
|
The exact mechanism is platform-specific and is an internal implementation |
|
|
detail (typically, a script or shell function will be used). |
|
|
|
|
|
|
|
|
.. _venv-api: |
|
|
|
|
|
API |
|
Expand Down
|
|