mirror of https://github.com/python/cpython
Docs: Update and proofread `library/venv.rst` (#124121)
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
This commit is contained in:
Hugo van Kemenade
GitHub
parent
b65f2cdfa7
commit
23e812b84a
|
|
@ -37,14 +37,14 @@ A virtual environment is (amongst other things):
|
|||
are by default isolated from software in other virtual environments and Python
|
||||
interpreters and libraries installed in the operating system.
|
||||
|
||||
* Contained in a directory, conventionally either named ``venv`` or ``.venv`` in
|
||||
* Contained in a directory, conventionally named ``.venv`` or ``venv`` in
|
||||
the project directory, or under a container directory for lots of virtual
|
||||
environments, such as ``~/.virtualenvs``.
|
||||
|
||||
* Not checked into source control systems such as Git.
|
||||
|
||||
* Considered as disposable -- it should be simple to delete and recreate it from
|
||||
scratch. You don't place any project code in the environment
|
||||
scratch. You don't place any project code in the environment.
|
||||
|
||||
* Not considered as movable or copyable -- you just recreate the same
|
||||
environment in the target location.
|
||||
|
|
@ -61,7 +61,127 @@ See :pep:`405` for more background on Python virtual environments.
|
|||
Creating virtual environments
|
||||
-----------------------------
|
||||
|
||||
.. include:: /using/venv-create.inc
|
||||
:ref:`Virtual environments <venv-def>` are created by executing the ``venv``
|
||||
module:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
python -m venv /path/to/new/virtual/environment
|
||||
|
||||
This creates the target directory (including parent directories as needed)
|
||||
and places a :file:`pyvenv.cfg` file in it with a ``home`` key
|
||||
pointing to the Python installation from which the command was run.
|
||||
It also creates a :file:`bin` (or :file:`Scripts` on Windows) subdirectory
|
||||
containing a copy or symlink of the Python executable
|
||||
(as appropriate for the platform or arguments used at environment creation time).
|
||||
It also creates a :file:`lib/pythonX.Y/site-packages` subdirectory
|
||||
(on Windows, this is :file:`Lib\site-packages`).
|
||||
If an existing directory is specified, it will be re-used.
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
The use of ``venv`` is now recommended for creating virtual environments.
|
||||
|
||||
.. deprecated-removed:: 3.6 3.8
|
||||
:program:`pyvenv` was the recommended tool for creating virtual environments
|
||||
for Python 3.3 and 3.4, and replaced in 3.5 by executing ``venv`` directly.
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
On Windows, invoke the ``venv`` command as follows:
|
||||
|
||||
.. code-block:: ps1con
|
||||
|
||||
PS> python -m venv C:\path\to\new\virtual\environment
|
||||
|
||||
The command, if run with ``-h``, will show the available options::
|
||||
|
||||
usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
|
||||
[--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
|
||||
[--without-scm-ignore-files]
|
||||
ENV_DIR [ENV_DIR ...]
|
||||
|
||||
Creates virtual Python environments in one or more target directories.
|
||||
|
||||
positional arguments:
|
||||
ENV_DIR A directory to create the environment in.
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
--system-site-packages
|
||||
Give the virtual environment access to the system
|
||||
site-packages dir.
|
||||
--symlinks Try to use symlinks rather than copies, when
|
||||
symlinks are not the default for the platform.
|
||||
--copies Try to use copies rather than symlinks, even when
|
||||
symlinks are the default for the platform.
|
||||
--clear Delete the contents of the environment directory
|
||||
if it already exists, before environment creation.
|
||||
--upgrade Upgrade the environment directory to use this
|
||||
version of Python, assuming Python has been
|
||||
upgraded in-place.
|
||||
--without-pip Skips installing or upgrading pip in the virtual
|
||||
environment (pip is bootstrapped by default)
|
||||
--prompt PROMPT Provides an alternative prompt prefix for this
|
||||
environment.
|
||||
--upgrade-deps Upgrade core dependencies (pip) to the latest
|
||||
version in PyPI
|
||||
--without-scm-ignore-files
|
||||
Skips adding SCM ignore files to the environment
|
||||
directory (Git is supported by default).
|
||||
|
||||
Once an environment has been created, you may wish to activate it, e.g. by
|
||||
sourcing an activate script in its bin directory.
|
||||
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
Installs pip by default, added the ``--without-pip`` and ``--copies``
|
||||
options.
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
In earlier versions, if the target directory already existed, an error was
|
||||
raised, unless the ``--clear`` or ``--upgrade`` option was provided.
|
||||
|
||||
.. versionchanged:: 3.9
|
||||
Add ``--upgrade-deps`` option to upgrade pip + setuptools to the latest on PyPI.
|
||||
|
||||
.. versionchanged:: 3.12
|
||||
|
||||
``setuptools`` is no longer a core venv dependency.
|
||||
|
||||
.. versionchanged:: 3.13
|
||||
|
||||
Added the ``--without-scm-ignore-files`` option.
|
||||
.. versionchanged:: 3.13
|
||||
``venv`` now creates a :file:`.gitignore` file for Git by default.
|
||||
|
||||
.. note::
|
||||
While symlinks are supported on Windows, they are not recommended. Of
|
||||
particular note is that double-clicking ``python.exe`` in File Explorer
|
||||
will resolve the symlink eagerly and ignore the virtual environment.
|
||||
|
||||
.. note::
|
||||
On Microsoft Windows, it may be required to enable the ``Activate.ps1``
|
||||
script by setting the execution policy for the user. You can do this by
|
||||
issuing the following PowerShell command:
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||||
|
||||
See `About Execution Policies
|
||||
<https://go.microsoft.com/fwlink/?LinkID=135170>`_
|
||||
for more information.
|
||||
|
||||
The created :file:`pyvenv.cfg` file also includes the
|
||||
``include-system-site-packages`` key, set to ``true`` if ``venv`` is
|
||||
run with the ``--system-site-packages`` option, ``false`` otherwise.
|
||||
|
||||
Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be
|
||||
invoked to bootstrap ``pip`` into the virtual environment.
|
||||
|
||||
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.
|
||||
|
||||
.. _venv-explanation:
|
||||
|
||||
|
|
@ -117,7 +237,7 @@ 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`.
|
||||
: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
|
||||
|
|
@ -345,8 +465,8 @@ creation according to their needs, the :class:`EnvBuilder` class.
|
|||
.. method:: install_scripts(context, path)
|
||||
|
||||
*path* is the path to a directory that should contain subdirectories
|
||||
"common", "posix", "nt", each containing scripts destined for the bin
|
||||
directory in the environment. The contents of "common" and the
|
||||
``common``, ``posix``, ``nt``; each containing scripts destined for the
|
||||
``bin`` directory in the environment. The contents of ``common`` and the
|
||||
directory corresponding to :data:`os.name` are copied after some text
|
||||
replacement of placeholders:
|
||||
|
||||
|
|
@ -371,7 +491,7 @@ creation according to their needs, the :class:`EnvBuilder` class.
|
|||
.. method:: create_git_ignore_file(context)
|
||||
|
||||
Creates a ``.gitignore`` file within the virtual environment that causes
|
||||
the entire directory to be ignored by the ``git`` source control manager.
|
||||
the entire directory to be ignored by the Git source control manager.
|
||||
|
||||
.. versionadded:: 3.13
|
||||
|
||||
|
|
@ -387,16 +507,16 @@ There is also a module-level convenience function:
|
|||
.. versionadded:: 3.3
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
Added the ``with_pip`` parameter
|
||||
Added the *with_pip* parameter
|
||||
|
||||
.. versionchanged:: 3.6
|
||||
Added the ``prompt`` parameter
|
||||
Added the *prompt* parameter
|
||||
|
||||
.. versionchanged:: 3.9
|
||||
Added the ``upgrade_deps`` parameter
|
||||
Added the *upgrade_deps* parameter
|
||||
|
||||
.. versionchanged:: 3.13
|
||||
Added the ``scm_ignore_files`` parameter
|
||||
Added the *scm_ignore_files* parameter
|
||||
|
||||
An example of extending ``EnvBuilder``
|
||||
--------------------------------------
|
||||
|
|
|
|||
|
|
@ -1,121 +0,0 @@
|
|||
Creation of :ref:`virtual environments <venv-def>` is done by executing the
|
||||
command ``venv``::
|
||||
|
||||
python -m venv /path/to/new/virtual/environment
|
||||
|
||||
Running this command creates the target directory (creating any parent
|
||||
directories that don't exist already) and places a ``pyvenv.cfg`` file in it
|
||||
with a ``home`` key pointing to the Python installation from which the command
|
||||
was run (a common name for the target directory is ``.venv``). It also creates
|
||||
a ``bin`` (or ``Scripts`` on Windows) subdirectory containing a copy/symlink
|
||||
of the Python binary/binaries (as appropriate for the platform or arguments
|
||||
used at environment creation time). It also creates an (initially empty)
|
||||
``lib/pythonX.Y/site-packages`` subdirectory (on Windows, this is
|
||||
``Lib\site-packages``). If an existing directory is specified, it will be
|
||||
re-used.
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
The use of ``venv`` is now recommended for creating virtual environments.
|
||||
|
||||
.. deprecated:: 3.6
|
||||
``pyvenv`` was the recommended tool for creating virtual environments for
|
||||
Python 3.3 and 3.4, and is
|
||||
:ref:`deprecated in Python 3.6 <whatsnew36-venv>`.
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
On Windows, invoke the ``venv`` command as follows::
|
||||
|
||||
c:\>Python35\python -m venv c:\path\to\myenv
|
||||
|
||||
Alternatively, if you configured the ``PATH`` and ``PATHEXT`` variables for
|
||||
your :ref:`Python installation <using-on-windows>`::
|
||||
|
||||
c:\>python -m venv c:\path\to\myenv
|
||||
|
||||
The command, if run with ``-h``, will show the available options::
|
||||
|
||||
usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
|
||||
[--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
|
||||
[--without-scm-ignore-file]
|
||||
ENV_DIR [ENV_DIR ...]
|
||||
|
||||
Creates virtual Python environments in one or more target directories.
|
||||
|
||||
positional arguments:
|
||||
ENV_DIR A directory to create the environment in.
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
--system-site-packages
|
||||
Give the virtual environment access to the system
|
||||
site-packages dir.
|
||||
--symlinks Try to use symlinks rather than copies, when
|
||||
symlinks are not the default for the platform.
|
||||
--copies Try to use copies rather than symlinks, even when
|
||||
symlinks are the default for the platform.
|
||||
--clear Delete the contents of the environment directory if
|
||||
it already exists, before environment creation.
|
||||
--upgrade Upgrade the environment directory to use this
|
||||
version of Python, assuming Python has been upgraded
|
||||
in-place.
|
||||
--without-pip Skips installing or upgrading pip in the virtual
|
||||
environment (pip is bootstrapped by default)
|
||||
--prompt PROMPT Provides an alternative prompt prefix for this
|
||||
environment.
|
||||
--upgrade-deps Upgrade core dependencies (pip) to the latest
|
||||
version in PyPI
|
||||
--without-scm-ignore-file
|
||||
Skips adding the default SCM ignore file to the
|
||||
environment directory (the default is a .gitignore
|
||||
file).
|
||||
|
||||
Once an environment has been created, you may wish to activate it, e.g. by
|
||||
sourcing an activate script in its bin directory.
|
||||
|
||||
.. versionchanged:: 3.13
|
||||
|
||||
``--without-scm-ignore-file`` was added along with creating an ignore file
|
||||
for ``git`` by default.
|
||||
|
||||
.. versionchanged:: 3.12
|
||||
|
||||
``setuptools`` is no longer a core venv dependency.
|
||||
|
||||
.. versionchanged:: 3.9
|
||||
Add ``--upgrade-deps`` option to upgrade pip + setuptools to the latest on PyPI
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
Installs pip by default, added the ``--without-pip`` and ``--copies``
|
||||
options
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
In earlier versions, if the target directory already existed, an error was
|
||||
raised, unless the ``--clear`` or ``--upgrade`` option was provided.
|
||||
|
||||
.. note::
|
||||
While symlinks are supported on Windows, they are not recommended. Of
|
||||
particular note is that double-clicking ``python.exe`` in File Explorer
|
||||
will resolve the symlink eagerly and ignore the virtual environment.
|
||||
|
||||
.. note::
|
||||
On Microsoft Windows, it may be required to enable the ``Activate.ps1``
|
||||
script by setting the execution policy for the user. You can do this by
|
||||
issuing the following PowerShell command:
|
||||
|
||||
PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||||
|
||||
See `About Execution Policies
|
||||
<https://go.microsoft.com/fwlink/?LinkID=135170>`_
|
||||
for more information.
|
||||
|
||||
The created ``pyvenv.cfg`` file also includes the
|
||||
``include-system-site-packages`` key, set to ``true`` if ``venv`` is
|
||||
run with the ``--system-site-packages`` option, ``false`` otherwise.
|
||||
|
||||
Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be
|
||||
invoked to bootstrap ``pip`` into the virtual environment.
|
||||
|
||||
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.
|
||||
Loading…
Reference in New Issue