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.
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:
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
.. 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:
.. 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
.. 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``
--------------------------------------
+++ /dev/null
-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.
projects / thirdparty / Python / cpython.git / commitdiff
