Skip to content

Commit

Permalink
[3.10] [doc] Refresh the venv introduction documentation, and correct…
Browse files Browse the repository at this point in the history 
… the statement about VIRTUAL_ENV (pythonGH-98350)

Co-authored-by: C.A.M. Gerlach <[email protected]>
(cherry picked from commit 1a6bacb)
  • Loading branch information
@pelson @vsajip
pelson authored and vsajip committed Oct 19, 2022
1 parent ac2e7be commit 4d2eb7b
Show file tree
Hide file tree
Showing 2 changed files with 135 additions and 100 deletions.
193 changes: 135 additions & 58 deletions Doc/library/venv.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,74 +15,101 @@

--------------

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:
.. _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.

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 information about Python virtual environments.
See :pep:`405` for more background on Python virtual environments.

.. seealso::

`Python Packaging User Guide: Creating and using virtual environments
<https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment>`__

.. include:: ../includes/wasm-notavail.rst

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 :mod:`distutils` 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 @@ -98,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 Expand Up @@ -183,11 +215,56 @@ creation according to their needs, the :class:`EnvBuilder` class.

.. method:: ensure_directories(env_dir)

Creates the environment directory and all necessary directories, and
returns a context object. This is just a holder for attributes (such as
paths), for use by the other methods. The directories are allowed to
exist already, as long as either ``clear`` or ``upgrade`` were
specified to allow operating on an existing environment directory.
Creates the environment directory and all necessary subdirectories that
don't already exist, and returns a context object. This context object
is just a holder for attributes (such as paths) for use by the other
methods. If the :class:`EnvBuilder` is created with the arg
``clear=True``, contents of the environment directory will be cleared
and then all necessary subdirectories will be recreated.

The returned context object is a :class:`types.SimpleNamespace` with the
following attributes:

* ``env_dir`` - The location of the virtual environment. Used for
``__VENV_DIR__`` in activation scripts (see :meth:`install_scripts`).

* ``env_name`` - The name of the virtual environment. Used for
``__VENV_NAME__`` in activation scripts (see :meth:`install_scripts`).

* ``prompt`` - The prompt to be used by the activation scripts. Used for
``__VENV_PROMPT__`` in activation scripts (see :meth:`install_scripts`).

* ``executable`` - The underlying Python executable used by the virtual
environment. This takes into account the case where a virtual environment
is created from another virtual environment.

* ``inc_path`` - The include path for the virtual environment.

* ``lib_path`` - The purelib path for the virtual environment.

* ``bin_path`` - The script path for the virtual environment.

* ``bin_name`` - The name of the script path relative to the virtual
environment location. Used for ``__VENV_BIN_NAME__`` in activation
scripts (see :meth:`install_scripts`).

* ``env_exe`` - The name of the Python interpreter in the virtual
environment. Used for ``__VENV_PYTHON__`` in activation scripts
(see :meth:`install_scripts`).

* ``env_exec_cmd`` - The name of the Python interpreter, taking into
account filesystem redirections. This can be used to run Python in
the virtual environment.


.. versionchanged:: 3.12
The attribute ``lib_path`` was added to the context, and the context
object was documented.

.. versionchanged:: 3.11
The *venv*
:ref:`sysconfig installation scheme <installation_paths>`
is used to construct the paths of the created directories.

.. method:: create_configuration(context)

Expand Down
42 changes: 0 additions & 42 deletions Doc/using/venv-create.inc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -105,45 +105,3 @@ Multiple paths can be given to ``venv``, in which case an identical virtual
environment will be created, according to the given options, at each provided
path.
Once a virtual environment has been created, it can be "activated" using a
script in the virtual environment's binary directory. The invocation of the
script is platform-specific (`<venv>` must be replaced by the path of the
directory containing the virtual environment):

+-------------+-----------------+-----------------------------------------+
| Platform | Shell | Command to activate virtual environment |
+=============+=================+=========================================+
| POSIX | bash/zsh | $ source <venv>/bin/activate |
+-------------+-----------------+-----------------------------------------+
| | fish | $ source <venv>/bin/activate.fish |
+-------------+-----------------+-----------------------------------------+
| | csh/tcsh | $ source <venv>/bin/activate.csh |
+-------------+-----------------+-----------------------------------------+
| | PowerShell Core | $ <venv>/bin/Activate.ps1 |
+-------------+-----------------+-----------------------------------------+
| Windows | cmd.exe | C:\\> <venv>\\Scripts\\activate.bat |
+-------------+-----------------+-----------------------------------------+
| | PowerShell | PS C:\\> <venv>\\Scripts\\Activate.ps1 |
+-------------+-----------------+-----------------------------------------+

When a virtual environment is active, the :envvar:`VIRTUAL_ENV` environment
variable is set to the path of the virtual environment. This can be used to
check if one is running inside a virtual environment.

You don't specifically *need* to activate an environment; activation just
prepends the virtual environment's binary directory to your path, so that
"python" invokes the virtual environment's Python interpreter and you can run
installed scripts without having to use their full path. However, all scripts
installed in a virtual environment should be runnable without activating it,
and run with the virtual environment's Python automatically.
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).
.. versionadded:: 3.4
``fish`` and ``csh`` activation scripts.
.. versionadded:: 3.8
PowerShell activation scripts installed under POSIX for PowerShell Core
support.

0 comments on commit 4d2eb7b

Please sign in to comment.