mirror of
https://github.com/python/cpython.git
synced 2025-12-23 09:19:18 +00:00
[3.10] [doc] Refresh the venv introduction documentation, and correct… (GH-98466)
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> Co-authored-by: Phil Elson <pelson.pub@gmail.com>
This commit is contained in:
Vinay Sajip
GitHub
parent
ac2e7bec08
commit
dddbbd9e3e
2 changed files with 129 additions and 96 deletions
|
|
@ -15,74 +15,99 @@
|
|||
|
||||
--------------
|
||||
|
||||
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:
|
||||
|
||||
See :pep:`405` for more information about Python virtual environments.
|
||||
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 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.
|
||||
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 is a directory tree which contains Python executable
|
||||
files and other files which indicate that it is 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):
|
||||
|
||||
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.
|
||||
+-------------+------------+--------------------------------------------------+
|
||||
| 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` |
|
||||
+-------------+------------+--------------------------------------------------+
|
||||
|
||||
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).
|
||||
.. versionadded:: 3.4
|
||||
:program:`!fish` and :program:`!csh` activation scripts.
|
||||
|
||||
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.
|
||||
.. versionadded:: 3.8
|
||||
PowerShell activation scripts installed under POSIX for PowerShell Core
|
||||
support.
|
||||
|
||||
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``.
|
||||
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
|
||||
|
|
@ -98,6 +123,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
|
||||
|
|
@ -183,11 +213,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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue