Issue #27285: Document the deprecation of the pyvenv script.
As part of the update, the documentation was updated to normalize
around the term "virtual environment" instead of relying too heavily
on "venv" for the same meaning and leading to inconsistent usage of
either.
Thanks to Steve Piercy for the patch.
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index fe17595..3d05c14 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -970,7 +970,7 @@
without interfering with the behaviour of other Python applications
running on the same system.
- See also :ref:`scripts-pyvenv`.
+ See also :mod:`venv`.
virtual machine
A computer defined entirely in software. Python's virtual machine
diff --git a/Doc/installing/index.rst b/Doc/installing/index.rst
index 1ef3149..b22465d 100644
--- a/Doc/installing/index.rst
+++ b/Doc/installing/index.rst
@@ -2,9 +2,9 @@
.. _installing-index:
-*****************************
- Installing Python Modules
-*****************************
+*************************
+Installing Python Modules
+*************************
:Email: distutils-sig@python.org
@@ -34,24 +34,24 @@
* ``pip`` is the preferred installer program. Starting with Python 3.4, it
is included by default with the Python binary installers.
-* a virtual environment is a semi-isolated Python environment that allows
+* A *virtual environment* is a semi-isolated Python environment that allows
packages to be installed for use by a particular application, rather than
- being installed system wide
-* ``pyvenv`` is the standard tool for creating virtual environments, and has
+ being installed system wide.
+* ``venv`` is the standard tool for creating virtual environments, and has
been part of Python since Python 3.3. Starting with Python 3.4, it
- defaults to installing ``pip`` into all created virtual environments
+ defaults to installing ``pip`` into all created virtual environments.
* ``virtualenv`` is a third party alternative (and predecessor) to
- ``pyvenv``. It allows virtual environments to be used on versions of
- Python prior to 3.4, which either don't provide ``pyvenv`` at all, or
+ ``venv``. It allows virtual environments to be used on versions of
+ Python prior to 3.4, which either don't provide ``venv`` at all, or
aren't able to automatically install ``pip`` into created environments.
-* the `Python Packaging Index <https://pypi.python.org/pypi>`__ is a public
+* The `Python Packaging Index <https://pypi.python.org/pypi>`__ is a public
repository of open source licensed packages made available for use by
- other Python users
+ other Python users.
* the `Python Packaging Authority
<https://www.pypa.io/en/latest/>`__ are the group of
developers and documentation authors responsible for the maintenance and
evolution of the standard packaging tools and the associated metadata and
- file format standards. They maintain a variety of tools, documentation
+ file format standards. They maintain a variety of tools, documentation,
and issue trackers on both `GitHub <https://github.com/pypa>`__ and
`BitBucket <https://bitbucket.org/pypa/>`__.
* ``distutils`` is the original build and distribution system first added to
@@ -62,6 +62,19 @@
of the mailing list used to coordinate Python packaging standards
development).
+.. 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/installing/#creating-virtual-environments>`__
+
Basic usage
===========
@@ -100,13 +113,14 @@
More information and resources regarding ``pip`` and its capabilities can be
found in the `Python Packaging User Guide <https://packaging.python.org>`__.
-``pyvenv`` has its own documentation at :ref:`scripts-pyvenv`. Installing
-into an active virtual environment uses the commands shown above.
+Creation of virtual environments is done through the :mod:`venv` module.
+Installing packages into an active virtual environment uses the commands shown
+above.
.. seealso::
`Python Packaging User Guide: Installing Python Distribution Packages
- <https://packaging.python.org/en/latest/installing/>`__
+ <https://packaging.python.org/installing/>`__
How do I ...?
@@ -124,7 +138,7 @@
.. seealso::
`Python Packaging User Guide: Requirements for Installing Packages
- <https://packaging.python.org/en/latest/installing/#requirements-for-installing-packages>`__
+ <https://packaging.python.org/installing/#requirements-for-installing-packages>`__
.. installing-per-user-installation:
@@ -142,20 +156,19 @@
A number of scientific Python packages have complex binary dependencies, and
aren't currently easy to install using ``pip`` directly. At this point in
time, it will often be easier for users to install these packages by
-`other means
-<https://packaging.python.org/en/latest/science/>`__
+`other means <https://packaging.python.org/science/>`__
rather than attempting to install them with ``pip``.
.. seealso::
`Python Packaging User Guide: Installing Scientific Packages
- <https://packaging.python.org/en/latest/science/>`__
+ <https://packaging.python.org/science/>`__
... work with multiple versions of Python installed in parallel?
----------------------------------------------------------------
-On Linux, Mac OS X and other POSIX systems, use the versioned Python commands
+On Linux, Mac OS X, and other POSIX systems, use the versioned Python commands
in combination with the ``-m`` switch to run the appropriate copy of
``pip``::
@@ -164,7 +177,7 @@
python3 -m pip install SomePackage # default Python 3
python3.4 -m pip install SomePackage # specifically Python 3.4
-(appropriately versioned ``pip`` commands may also be available)
+Appropriately versioned ``pip`` commands may also be available.
On Windows, use the ``py`` Python launcher in combination with the ``-m``
switch::
@@ -212,11 +225,11 @@
than needing to build them themselves.
Some of the solutions for installing `scientific software
-<https://packaging.python.org/en/latest/science/>`__
-that is not yet available as pre-built ``wheel`` files may also help with
+<https://packaging.python.org/science/>`__
+that are not yet available as pre-built ``wheel`` files may also help with
obtaining other binary extensions without needing to build them locally.
.. seealso::
`Python Packaging User Guide: Binary Extensions
- <https://packaging.python.org/en/latest/extensions/>`__
+ <https://packaging.python.org/extensions/>`__
diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
index af4a6d1..02e36fd 100644
--- a/Doc/library/venv.rst
+++ b/Doc/library/venv.rst
@@ -31,44 +31,50 @@
.. _venv-def:
-.. note:: A virtual environment (also called a ``venv``) 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.
+.. 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 venv is a directory tree which contains Python executable files and
- other files which indicate that it is a venv.
+ 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 venvs - i.e. when a venv is active, they install Python
- packages into the venv without needing to be told to do so explicitly.
+ 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 venv is active (i.e. the venv's Python interpreter is running), the
- attributes :attr:`sys.prefix` and :attr:`sys.exec_prefix` point to the base
- directory of the venv, whereas :attr:`sys.base_prefix` and
- :attr:`sys.base_exec_prefix` point to the non-venv Python installation
- which was used to create the venv. If a venv 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-venv Python installation).
+ 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 venv is active, any options that change the installation path will be
- ignored from all distutils configuration files to prevent projects being
- inadvertently installed outside of the virtual environment.
+ When a virtual environment is active, any options that change the
+ installation path will be ignored from all distutils configuration files to
+ prevent projects being inadvertently installed outside of the virtual
+ environment.
- When working in a command shell, users can make a venv active by running an
- ``activate`` script in the venv's executables directory (the precise filename
- is shell-dependent), which prepends the venv's directory for executables to
- the ``PATH`` environment variable for the running shell. There should be no
- need in other circumstances to activate a venv -- scripts installed into
- venvs have a shebang line which points to the venv'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 venv in ``PATH``.
+ 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 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``.
.. _venv-api:
@@ -219,7 +225,7 @@
--------------------------------------
The following script shows how to extend :class:`EnvBuilder` by implementing a
-subclass which installs setuptools and pip into a created venv::
+subclass which installs setuptools and pip into a created virtual environment::
import os
import os.path
@@ -233,12 +239,12 @@
class ExtendedEnvBuilder(venv.EnvBuilder):
"""
This builder installs setuptools and pip so that you can pip or
- easy_install other packages into the created environment.
+ easy_install other packages into the created virtual environment.
:param nodist: If True, setuptools and pip are not installed into the
- created environment.
+ created virtual environment.
:param nopip: If True, pip is not installed into the created
- environment.
+ virtual environment.
:param progress: If setuptools or pip are installed, the progress of the
installation can be monitored by passing a progress
callable. If specified, it is called with two
@@ -264,10 +270,10 @@
def post_setup(self, context):
"""
Set up any packages which need to be pre-installed into the
- environment being created.
+ virtual environment being created.
- :param context: The information for the environment creation request
- being processed.
+ :param context: The information for the virtual environment
+ creation request being processed.
"""
os.environ['VIRTUAL_ENV'] = context.env_dir
if not self.nodist:
@@ -301,7 +307,7 @@
fn = os.path.split(path)[-1]
binpath = context.bin_path
distpath = os.path.join(binpath, fn)
- # Download script into the env's binaries folder
+ # Download script into the virtual environment's binaries folder
urlretrieve(url, distpath)
progress = self.progress
if self.verbose:
@@ -313,7 +319,7 @@
else:
sys.stderr.write('Installing %s ...%s' % (name, term))
sys.stderr.flush()
- # Install in the env
+ # Install in the virtual environment
args = [context.env_exe, fn]
p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath)
t1 = Thread(target=self.reader, args=(p.stdout, 'stdout'))
@@ -332,10 +338,10 @@
def install_setuptools(self, context):
"""
- Install setuptools in the environment.
+ Install setuptools in the virtual environment.
- :param context: The information for the environment creation request
- being processed.
+ :param context: The information for the virtual environment
+ creation request being processed.
"""
url = 'https://bitbucket.org/pypa/setuptools/downloads/ez_setup.py'
self.install_script(context, 'setuptools', url)
@@ -348,10 +354,10 @@
def install_pip(self, context):
"""
- Install pip in the environment.
+ Install pip in the virtual environment.
- :param context: The information for the environment creation request
- being processed.
+ :param context: The information for the virtual environment
+ creation request being processed.
"""
url = 'https://raw.github.com/pypa/pip/master/contrib/get-pip.py'
self.install_script(context, 'pip', url)
@@ -374,7 +380,8 @@
'more target '
'directories.')
parser.add_argument('dirs', metavar='ENV_DIR', nargs='+',
- help='A directory to create the environment in.')
+ help='A directory in which to create the
+ 'virtual environment.')
parser.add_argument('--no-setuptools', default=False,
action='store_true', dest='nodist',
help="Don't install setuptools or pip in the "
@@ -398,14 +405,17 @@
'the platform.')
parser.add_argument('--clear', default=False, action='store_true',
dest='clear', help='Delete the contents of the '
- 'environment directory if it '
- 'already exists, before '
+ 'virtual environment '
+ 'directory if it already '
+ 'exists, before virtual '
'environment creation.')
parser.add_argument('--upgrade', default=False, action='store_true',
- dest='upgrade', help='Upgrade the environment '
- 'directory to use this version '
- 'of Python, assuming Python '
- 'has been upgraded in-place.')
+ dest='upgrade', help='Upgrade the virtual '
+ 'environment directory to '
+ 'use this version of '
+ 'Python, assuming Python '
+ 'has been upgraded '
+ 'in-place.')
parser.add_argument('--verbose', default=False, action='store_true',
dest='verbose', help='Display the output '
'from the scripts which '
diff --git a/Doc/tutorial/venv.rst b/Doc/tutorial/venv.rst
index 3b2ee2e..e2dd57d 100644
--- a/Doc/tutorial/venv.rst
+++ b/Doc/tutorial/venv.rst
@@ -20,15 +20,14 @@
the requirements are in conflict and installing either version 1.0 or 2.0
will leave one application unable to run.
-The solution for this problem is to create a :term:`virtual
-environment` (often shortened to "virtualenv"), a self-contained
-directory tree that contains a Python installation for a particular
-version of Python, plus a number of additional packages.
+The solution for this problem is to create a :term:`virtual environment`, a
+self-contained directory tree that contains a Python installation for a
+particular version of Python, plus a number of additional packages.
Different applications can then use different virtual environments.
To resolve the earlier example of conflicting requirements,
application A can have its own virtual environment with version 1.0
-installed while application B has another virtualenv with version 2.0.
+installed while application B has another virtual environment with version 2.0.
If application B requires a library be upgraded to version 3.0, this will
not affect application A's environment.
@@ -36,29 +35,26 @@
Creating Virtual Environments
=============================
-The script used to create and manage virtual environments is called
-:program:`pyvenv`. :program:`pyvenv` will usually install the most
-recent version of Python that you have available; the script is also
-installed with a version number, so if you have multiple versions of
-Python on your system you can select a specific Python version by
-running ``pyvenv-3.4`` or whichever version you want.
+The module used to create and manage virtual environments is called
+:mod:`venv`. :mod:`venv` will usually install the most recent version of
+Python that you have available. If you have multiple versions of Python on your
+system, you can select a specific Python version by running ``python3`` or
+whichever version you want.
-To create a virtualenv, decide upon a directory
-where you want to place it and run :program:`pyvenv` with the
-directory path::
+To create a virtual environment, decide upon a directory where you want to
+place it, and run the :mod:`venv` module as a script with the directory path::
- pyvenv tutorial-env
+ python3 -m venv tutorial-env
This will create the ``tutorial-env`` directory if it doesn't exist,
and also create directories inside it containing a copy of the Python
interpreter, the standard library, and various supporting files.
-Once you've created a virtual environment, you need to
-activate it.
+Once you've created a virtual environment, you may activate it.
On Windows, run::
- tutorial-env/Scripts/activate
+ tutorial-env\Scripts\activate.bat
On Unix or MacOS, run::
@@ -69,33 +65,36 @@
``activate.csh`` and ``activate.fish`` scripts you should use
instead.)
-Activating the virtualenv will change your shell's prompt to show what
-virtualenv you're using, and modify the environment so that running
-``python`` will get you that particular version and installation of
-Python. For example::
+Activating the virtual environment will change your shell's prompt to show what
+virtual environment you're using, and modify the environment so that running
+``python`` will get you that particular version and installation of Python.
+For example:
- -> source ~/envs/tutorial-env/bin/activate
- (tutorial-env) -> python
- Python 3.4.3+ (3.4:c7b9645a6f35+, May 22 2015, 09:31:25)
+.. code-block:: bash
+
+ $ source ~/envs/tutorial-env/bin/activate
+ (tutorial-env) $ python
+ Python 3.5.1 (default, May 6 2016, 10:59:36)
...
>>> import sys
>>> sys.path
- ['', '/usr/local/lib/python34.zip', ...,
- '~/envs/tutorial-env/lib/python3.4/site-packages']
+ ['', '/usr/local/lib/python35.zip', ...,
+ '~/envs/tutorial-env/lib/python3.5/site-packages']
>>>
Managing Packages with pip
==========================
-Once you've activated a virtual environment, you can install, upgrade,
-and remove packages using a program called :program:`pip`. By default
-``pip`` will install packages from the Python Package Index,
-<https://pypi.python.org/pypi>. You can browse the Python Package Index
-by going to it in your web browser, or you can use ``pip``'s
-limited search feature::
+You can install, upgrade, and remove packages using a program called
+:program:`pip`. By default ``pip`` will install packages from the Python
+Package Index, <https://pypi.python.org/pypi>. You can browse the Python
+Package Index by going to it in your web browser, or you can use ``pip``'s
+limited search feature:
- (tutorial-env) -> pip search astronomy
+.. code-block:: bash
+
+ (tutorial-env) $ pip search astronomy
skyfield - Elegant astronomy for Python
gary - Galactic astronomy and gravitational dynamics.
novas - The United States Naval Observatory NOVAS astronomy library
@@ -107,9 +106,11 @@
"freeze", etc. (Consult the :ref:`installing-index` guide for
complete documentation for ``pip``.)
-You can install the latest version of a package by specifying a package's name::
+You can install the latest version of a package by specifying a package's name:
- -> pip install novas
+.. code-block:: bash
+
+ (tutorial-env) $ pip install novas
Collecting novas
Downloading novas-3.1.1.3.tar.gz (136kB)
Installing collected packages: novas
@@ -117,9 +118,11 @@
Successfully installed novas-3.1.1.3
You can also install a specific version of a package by giving the
-package name followed by ``==`` and the version number::
+package name followed by ``==`` and the version number:
- -> pip install requests==2.6.0
+.. code-block:: bash
+
+ (tutorial-env) $ pip install requests==2.6.0
Collecting requests==2.6.0
Using cached requests-2.6.0-py2.py3-none-any.whl
Installing collected packages: requests
@@ -128,9 +131,11 @@
If you re-run this command, ``pip`` will notice that the requested
version is already installed and do nothing. You can supply a
different version number to get that version, or you can run ``pip
-install --upgrade`` to upgrade the package to the latest version::
+install --upgrade`` to upgrade the package to the latest version:
- -> pip install --upgrade requests
+.. code-block:: bash
+
+ (tutorial-env) $ pip install --upgrade requests
Collecting requests
Installing collected packages: requests
Found existing installation: requests 2.6.0
@@ -141,9 +146,11 @@
``pip uninstall`` followed by one or more package names will remove the
packages from the virtual environment.
-``pip show`` will display information about a particular package::
+``pip show`` will display information about a particular package:
- (tutorial-env) -> pip show requests
+.. code-block:: bash
+
+ (tutorial-env) $ pip show requests
---
Metadata-Version: 2.0
Name: requests
@@ -157,9 +164,11 @@
Requires:
``pip list`` will display all of the packages installed in the virtual
-environment::
+environment:
- (tutorial-env) -> pip list
+.. code-block:: bash
+
+ (tutorial-env) $ pip list
novas (3.1.1.3)
numpy (1.9.2)
pip (7.0.3)
@@ -168,19 +177,23 @@
``pip freeze`` will produce a similar list of the installed packages,
but the output uses the format that ``pip install`` expects.
-A common convention is to put this list in a ``requirements.txt`` file::
+A common convention is to put this list in a ``requirements.txt`` file:
- (tutorial-env) -> pip freeze > requirements.txt
- (tutorial-env) -> cat requirements.txt
+.. code-block:: bash
+
+ (tutorial-env) $ pip freeze > requirements.txt
+ (tutorial-env) $ cat requirements.txt
novas==3.1.1.3
numpy==1.9.2
requests==2.7.0
The ``requirements.txt`` can then be committed to version control and
shipped as part of an application. Users can then install all the
-necessary packages with ``install -r``::
+necessary packages with ``install -r``:
- -> pip install -r requirements.txt
+.. code-block:: bash
+
+ (tutorial-env) $ pip install -r requirements.txt
Collecting novas==3.1.1.3 (from -r requirements.txt (line 1))
...
Collecting numpy==1.9.2 (from -r requirements.txt (line 2))
diff --git a/Doc/using/index.rst b/Doc/using/index.rst
index 502afa9..a5df713 100644
--- a/Doc/using/index.rst
+++ b/Doc/using/index.rst
@@ -17,4 +17,3 @@
unix.rst
windows.rst
mac.rst
- scripts.rst
diff --git a/Doc/using/scripts.rst b/Doc/using/scripts.rst
deleted file mode 100644
index 2c87416..0000000
--- a/Doc/using/scripts.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-.. _tools-and-scripts:
-
-Additional Tools and Scripts
-============================
-
-.. _scripts-pyvenv:
-
-pyvenv - Creating virtual environments
---------------------------------------
-
-.. include:: venv-create.inc
-
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 @@
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)
+ -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``.
+ 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 @@
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 @@
+-------------+-----------------+-----------------------------------------+
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.
+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 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.
+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.