--------------
-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>`__
-
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
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
.. 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)
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.
projects / thirdparty / Python / cpython.git / commitdiff
