summaryrefslogtreecommitdiffstats
path: root/Doc/using/venv-create.inc
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/using/venv-create.inc')
-rw-r--r--Doc/using/venv-create.inc95
1 files changed, 53 insertions, 42 deletions
diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc
index 7ad3008..53f431b 100644
--- a/Doc/using/venv-create.inc
+++ b/Doc/using/venv-create.inc
@@ -1,31 +1,39 @@
Creation of :ref:`virtual environments <venv-def>` is done by executing the
-``pyvenv`` script::
+command ``venv``::
- pyvenv /path/to/new/virtual/environment
+ python3 -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 the command was run
-from. It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory
+with a ``home`` key pointing to the Python installation from which the command
+was run. It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory
containing a copy of the ``python`` binary (or binaries, in the case of
Windows). It also creates an (initially empty) ``lib/pythonX.Y/site-packages``
subdirectory (on Windows, this is ``Lib\site-packages``).
+.. deprecated:: 3.6
+ ``pyvenv`` was the recommended tool for creating virtual environments for
+ Python 3.3 and 3.4, and is `deprecated in Python 3.6
+ <https://docs.python.org/dev/whatsnew/3.6.html#deprecated-features>`_.
+
+.. versionchanged:: 3.5
+ The use of ``venv`` is now recommended for creating virtual environments.
+
.. seealso::
`Python Packaging User Guide: Creating and using virtual environments
- <https://packaging.python.org/en/latest/installing/#creating-virtual-environments>`__
+ <https://packaging.python.org/installing/#creating-virtual-environments>`__
.. highlight:: none
-On Windows, you may have to invoke the ``pyvenv`` script as follows, if you
-don't have the relevant PATH and PATHEXT settings::
+On Windows, invoke the ``venv`` command as follows::
- c:\Temp>c:\Python35\python c:\Python35\Tools\Scripts\pyvenv.py myenv
+ c:\>c:\Python35\python -m venv c:\path\to\myenv
-or equivalently::
+Alternatively, if you configured the ``PATH`` and ``PATHEXT`` variables for
+your :ref:`Python installation <using-on-windows>`::
- c:\Temp>c:\Python35\python -m venv myenv
+ c:\>python -m venv myenv c:\path\to\myenv
The command, if run with ``-h``, will show the available options::
@@ -36,25 +44,26 @@ The command, if run with ``-h``, will show the available options::
Creates virtual Python environments in one or more target directories.
positional arguments:
- ENV_DIR A directory to create the environment in.
+ ENV_DIR A directory to create the environment in.
optional arguments:
- -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)
-
-Depending on how the ``venv`` functionality has been invoked, the usage message
-may vary slightly, e.g. referencing ``pyvenv`` rather than ``venv``.
+ -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)
+
+ 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``
@@ -73,12 +82,13 @@ 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 ``pyvenv``, in which case an identical
-virtualenv will be created, according to the given options, at each
-provided path.
+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 venv has been created, it can be "activated" using a script in the
-venv's binary directory. The invocation of the script is platform-specific:
+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:
+-------------+-----------------+-----------------------------------------+
| Platform | Shell | Command to activate virtual environment |
@@ -95,16 +105,17 @@ venv's binary directory. The invocation of the script is platform-specific:
+-------------+-----------------+-----------------------------------------+
You don't specifically *need* to activate an environment; activation just
-prepends the venv's binary directory to your path, so that "python" invokes the
-venv's Python interpreter and you can run installed scripts without having to
-use their full path. However, all scripts installed in a venv should be
-runnable without activating it, and run with the venv's Python automatically.
-
-You can deactivate a venv by typing "deactivate" in your shell. The exact
-mechanism is platform-specific: for example, the Bash activation script defines
-a "deactivate" function, whereas on Windows there are separate scripts called
-``deactivate.bat`` and ``Deactivate.ps1`` which are installed when the venv is
-created.
+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: for example, the Bash activation
+script defines a "deactivate" function, whereas on Windows there are separate
+scripts called ``deactivate.bat`` and ``Deactivate.ps1`` which are installed
+when the virtual environment is created.
.. versionadded:: 3.4
``fish`` and ``csh`` activation scripts.