diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 40eccdec16b39ae..3a1fa2a835279bb 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -15,12 +15,22 @@ -------------- +.. _venv-def: + 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. +environments" with their own independent set of Python packages installed in +their site directories. A virtual environment is created on top of an existing +Python installation, known as the virtual environment's "base" Python, and may +be optionally isolated from the base's site packages, meaning +that packages installed in the base environment will not be accessible from +the virtual environment. +A virtual environment is therefore a powerful and convenient concept which +allows quick, and relatively light-weight, Python environment creation. + +When used from within a virtual environment, common installation tools such as +setuptools_ and pip_ will install Python packages +into the virtual environment's site directory without needing to be told to do +so explicitly. See :pep:`405` for more information about Python virtual environments. @@ -36,54 +46,66 @@ Creating virtual environments .. include:: /using/venv-create.inc - -.. _venv-def: - -.. 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``. +Further venv detail +------------------- + +When a virtual environment is running, the attributes :attr:`sys.prefix` and +:attr:`sys.exec_prefix` point to the prefix 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 (known as the +virtual environment's base environment). It is sufficient to check +``sys.prefix == sys.base_prefix`` to determine if the current interpreter is +a virtual environment. + +A virtual environment may be "activated" using a script in the virtual +environment's binary directory. This will prepend the virtual environment's +binary directory to your path, so that running "python" will invoke the virtual +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 (`` must be replaced by the path of the +directory containing the virtual environment): + ++-------------+-----------------+-----------------------------------------+ +| Platform | Shell | Command to activate virtual environment | ++=============+=================+=========================================+ +| POSIX | bash/zsh | $ source /bin/activate | ++-------------+-----------------+-----------------------------------------+ +| | fish | $ source /bin/activate.fish | ++-------------+-----------------+-----------------------------------------+ +| | csh/tcsh | $ source /bin/activate.csh | ++-------------+-----------------+-----------------------------------------+ +| | PowerShell Core | $ /bin/Activate.ps1 | ++-------------+-----------------+-----------------------------------------+ +| Windows | cmd.exe | C:\\> \\Scripts\\activate.bat | ++-------------+-----------------+-----------------------------------------+ +| | PowerShell | PS C:\\> \\Scripts\\Activate.ps1 | ++-------------+-----------------+-----------------------------------------+ + +.. versionadded:: 3.4 + ``fish`` and ``csh`` activation scripts. + +.. versionadded:: 3.8 + PowerShell activation scripts installed under POSIX for PowerShell Core + support. + +You don't specifically *need* to activate an environment, and all scripts +installed in a virtual 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 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 :envvar:`PATH`. + +When a virtual environment has been activated, the :envvar:`VIRTUAL_ENV` +environment variable is set to the path of the virtual environment. Since it +is not a requirement to explicitly activate a virtual environment in order +to use it, the :envvar:`VIRTUAL_ENV` environment variable cannot be relied +upon to determine whether a Python environment is virtual or not. .. warning:: Because scripts installed in environments should not expect the environment to be activated, their shebang lines contain the absolute paths @@ -99,6 +121,17 @@ 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). + + +.. note:: 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. + + .. _venv-api: API diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc index c2a9f521a148b6b..fd8cc019b4d1a83 100644 --- a/Doc/using/venv-create.inc +++ b/Doc/using/venv-create.inc @@ -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 (`` must be replaced by the path of the -directory containing the virtual environment): - -+-------------+-----------------+-----------------------------------------+ -| Platform | Shell | Command to activate virtual environment | -+=============+=================+=========================================+ -| POSIX | bash/zsh | $ source /bin/activate | -+-------------+-----------------+-----------------------------------------+ -| | fish | $ source /bin/activate.fish | -+-------------+-----------------+-----------------------------------------+ -| | csh/tcsh | $ source /bin/activate.csh | -+-------------+-----------------+-----------------------------------------+ -| | PowerShell Core | $ /bin/Activate.ps1 | -+-------------+-----------------+-----------------------------------------+ -| Windows | cmd.exe | C:\\> \\Scripts\\activate.bat | -+-------------+-----------------+-----------------------------------------+ -| | PowerShell | PS C:\\> \\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.