traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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.
This commit is contained in:
Brett Cannon 2016-07-08 10:46:21 -07:00
parent 53e22bfea5
commit 15552c39e0
9 changed files with 222 additions and 181 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Doc/glossary.rst
View File

@ -970,7 +970,7 @@ Glossary
without interfering with the behaviour of other Python applications without interfering with the behaviour of other Python applications
running on the same system. running on the same system.
See also :ref:`scripts-pyvenv`. See also :mod:`venv`.
virtual machine virtual machine
A computer defined entirely in software. Python's virtual machine A computer defined entirely in software. Python's virtual machine

61
Doc/installing/index.rst
View File

@ -2,9 +2,9 @@
.. _installing-index: .. _installing-index:
***************************** *************************
Installing Python Modules Installing Python Modules
***************************** *************************
:Email: distutils-sig@python.org :Email: distutils-sig@python.org
@ -34,24 +34,24 @@ Key terms
* ``pip`` is the preferred installer program. Starting with Python 3.4, it * ``pip`` is the preferred installer program. Starting with Python 3.4, it
is included by default with the Python binary installers. 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 packages to be installed for use by a particular application, rather than
being installed system wide being installed system wide.
* ``pyvenv`` is the standard tool for creating virtual environments, and has * ``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 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 * ``virtualenv`` is a third party alternative (and predecessor) to
``pyvenv``. It allows virtual environments to be used on versions of ``venv``. It allows virtual environments to be used on versions of
Python prior to 3.4, which either don't provide ``pyvenv`` at all, or Python prior to 3.4, which either don't provide ``venv`` at all, or
aren't able to automatically install ``pip`` into created environments. 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 repository of open source licensed packages made available for use by
other Python users other Python users.
* the `Python Packaging Authority * the `Python Packaging Authority
<https://www.pypa.io/en/latest/>`__ are the group of <https://www.pypa.io/en/latest/>`__ are the group of
developers and documentation authors responsible for the maintenance and developers and documentation authors responsible for the maintenance and
evolution of the standard packaging tools and the associated metadata 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 and issue trackers on both `GitHub <https://github.com/pypa>`__ and
`BitBucket <https://bitbucket.org/pypa/>`__. `BitBucket <https://bitbucket.org/pypa/>`__.
* ``distutils`` is the original build and distribution system first added to * ``distutils`` is the original build and distribution system first added to
@ -62,6 +62,19 @@ Key terms
of the mailing list used to coordinate Python packaging standards of the mailing list used to coordinate Python packaging standards
development). 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 Basic usage
=========== ===========
@ -100,13 +113,14 @@ explicitly::
More information and resources regarding ``pip`` and its capabilities can be More information and resources regarding ``pip`` and its capabilities can be
found in the `Python Packaging User Guide <https://packaging.python.org>`__. found in the `Python Packaging User Guide <https://packaging.python.org>`__.
``pyvenv`` has its own documentation at :ref:`scripts-pyvenv`. Installing Creation of virtual environments is done through the :mod:`venv` module.
into an active virtual environment uses the commands shown above. Installing packages into an active virtual environment uses the commands shown
above.
.. seealso:: .. seealso::
`Python Packaging User Guide: Installing Python Distribution Packages `Python Packaging User Guide: Installing Python Distribution Packages
<https://packaging.python.org/en/latest/installing/>`__ <https://packaging.python.org/installing/>`__
How do I ...? How do I ...?
@ -124,7 +138,7 @@ User Guide.
.. seealso:: .. seealso::
`Python Packaging User Guide: Requirements for Installing Packages `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: .. installing-per-user-installation:
@ -142,20 +156,19 @@ package just for the current user, rather than for all users of the system.
A number of scientific Python packages have complex binary dependencies, and A number of scientific Python packages have complex binary dependencies, and
aren't currently easy to install using ``pip`` directly. At this point in 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 time, it will often be easier for users to install these packages by
`other means `other means <https://packaging.python.org/science/>`__
<https://packaging.python.org/en/latest/science/>`__
rather than attempting to install them with ``pip``. rather than attempting to install them with ``pip``.
.. seealso:: .. seealso::
`Python Packaging User Guide: Installing Scientific Packages `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? ... 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 in combination with the ``-m`` switch to run the appropriate copy of
``pip``:: ``pip``::
@ -164,7 +177,7 @@ in combination with the ``-m`` switch to run the appropriate copy of
python3 -m pip install SomePackage # default Python 3 python3 -m pip install SomePackage # default Python 3
python3.4 -m pip install SomePackage # specifically Python 3.4 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`` On Windows, use the ``py`` Python launcher in combination with the ``-m``
switch:: switch::
@ -212,11 +225,11 @@ as users are more regularly able to install pre-built extensions rather
than needing to build them themselves. than needing to build them themselves.
Some of the solutions for installing `scientific software Some of the solutions for installing `scientific software
<https://packaging.python.org/en/latest/science/>`__ <https://packaging.python.org/science/>`__
that is not yet available as pre-built ``wheel`` files may also help with that are not yet available as pre-built ``wheel`` files may also help with
obtaining other binary extensions without needing to build them locally. obtaining other binary extensions without needing to build them locally.
.. seealso:: .. seealso::
`Python Packaging User Guide: Binary Extensions `Python Packaging User Guide: Binary Extensions
<https://packaging.python.org/en/latest/extensions/>`__ <https://packaging.python.org/extensions/>`__

118
Doc/library/venv.rst
View File

@ -31,44 +31,50 @@ Creating virtual environments
.. _venv-def: .. _venv-def:
.. note:: A virtual environment (also called a ``venv``) is a Python .. note:: A virtual environment is a Python environment such that the Python
environment such that the Python interpreter, libraries and scripts interpreter, libraries and scripts installed into it are isolated from those
installed into it are isolated from those installed in other virtual installed in other virtual environments, and (by default) any libraries
environments, and (by default) any libraries installed in a "system" Python, installed in a "system" Python, i.e., one which is installed as part of your
i.e. one which is installed as part of your operating system. operating system.
A venv is a directory tree which contains Python executable files and A virtual environment is a directory tree which contains Python executable
other files which indicate that it is a venv. files and other files which indicate that it is a virtual environment.
Common installation tools such as ``Setuptools`` and ``pip`` work as Common installation tools such as ``Setuptools`` and ``pip`` work as
expected with venvs - i.e. when a venv is active, they install Python expected with virtual environments. In other words, when a virtual
packages into the venv without needing to be told to do so explicitly. 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 When a virtual environment is active (i.e., the virtual environment's Python
attributes :attr:`sys.prefix` and :attr:`sys.exec_prefix` point to the base interpreter is running), the attributes :attr:`sys.prefix` and
directory of the venv, whereas :attr:`sys.base_prefix` and :attr:`sys.exec_prefix` point to the base directory of the virtual
:attr:`sys.base_exec_prefix` point to the non-venv Python installation environment, whereas :attr:`sys.base_prefix` and
which was used to create the venv. If a venv is not active, then :attr:`sys.base_exec_prefix` point to the non-virtual environment Python
:attr:`sys.prefix` is the same as :attr:`sys.base_prefix` and installation which was used to create the virtual environment. If a virtual
:attr:`sys.exec_prefix` is the same as :attr:`sys.base_exec_prefix` (they environment is not active, then :attr:`sys.prefix` is the same as
all point to a non-venv Python installation). :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 When a virtual environment is active, any options that change the
ignored from all distutils configuration files to prevent projects being installation path will be ignored from all distutils configuration files to
inadvertently installed outside of the virtual environment. 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 When working in a command shell, users can make a virtual environment active
``activate`` script in the venv's executables directory (the precise filename by running an ``activate`` script in the virtual environment's executables
is shell-dependent), which prepends the venv's directory for executables to directory (the precise filename is shell-dependent), which prepends the
the ``PATH`` environment variable for the running shell. There should be no virtual environment's directory for executables to the ``PATH`` environment
need in other circumstances to activate a venv -- scripts installed into variable for the running shell. There should be no need in other
venvs have a shebang line which points to the venv's Python interpreter. This circumstances to activate a virtual environment—scripts installed into
means that the script will run with that interpreter regardless of the value virtual environments have a "shebang" line which points to the virtual
of ``PATH``. On Windows, shebang line processing is supported if you have the environment's Python interpreter. This means that the script will run with
Python Launcher for Windows installed (this was added to Python in 3.3 - see that interpreter regardless of the value of ``PATH``. On Windows, "shebang"
:pep:`397` for more details). Thus, double-clicking an installed script in line processing is supported if you have the Python Launcher for Windows
a Windows Explorer window should run the script with the correct interpreter installed (this was added to Python in 3.3 - see :pep:`397` for more
without there needing to be any reference to its venv in ``PATH``. 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: .. _venv-api:
@ -219,7 +225,7 @@ An example of extending ``EnvBuilder``
-------------------------------------- --------------------------------------
The following script shows how to extend :class:`EnvBuilder` by implementing a 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
import os.path import os.path
@ -233,12 +239,12 @@ subclass which installs setuptools and pip into a created venv::
class ExtendedEnvBuilder(venv.EnvBuilder): class ExtendedEnvBuilder(venv.EnvBuilder):
""" """
This builder installs setuptools and pip so that you can pip or 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 :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 :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 :param progress: If setuptools or pip are installed, the progress of the
installation can be monitored by passing a progress installation can be monitored by passing a progress
callable. If specified, it is called with two callable. If specified, it is called with two
@ -264,10 +270,10 @@ subclass which installs setuptools and pip into a created venv::
def post_setup(self, context): def post_setup(self, context):
""" """
Set up any packages which need to be pre-installed into the 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 :param context: The information for the virtual environment
being processed. creation request being processed.
""" """
os.environ['VIRTUAL_ENV'] = context.env_dir os.environ['VIRTUAL_ENV'] = context.env_dir
if not self.nodist: if not self.nodist:
@ -301,7 +307,7 @@ subclass which installs setuptools and pip into a created venv::
fn = os.path.split(path)[-1] fn = os.path.split(path)[-1]
binpath = context.bin_path binpath = context.bin_path
distpath = os.path.join(binpath, fn) 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) urlretrieve(url, distpath)
progress = self.progress progress = self.progress
if self.verbose: if self.verbose:
@ -313,7 +319,7 @@ subclass which installs setuptools and pip into a created venv::
else: else:
sys.stderr.write('Installing %s ...%s' % (name, term)) sys.stderr.write('Installing %s ...%s' % (name, term))
sys.stderr.flush() sys.stderr.flush()
# Install in the env # Install in the virtual environment
args = [context.env_exe, fn] args = [context.env_exe, fn]
p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath) p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath)
t1 = Thread(target=self.reader, args=(p.stdout, 'stdout')) t1 = Thread(target=self.reader, args=(p.stdout, 'stdout'))
@ -332,10 +338,10 @@ subclass which installs setuptools and pip into a created venv::
def install_setuptools(self, context): 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 :param context: The information for the virtual environment
being processed. creation request being processed.
""" """
url = 'https://bitbucket.org/pypa/setuptools/downloads/ez_setup.py' url = 'https://bitbucket.org/pypa/setuptools/downloads/ez_setup.py'
self.install_script(context, 'setuptools', url) self.install_script(context, 'setuptools', url)
@ -348,10 +354,10 @@ subclass which installs setuptools and pip into a created venv::
def install_pip(self, context): 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 :param context: The information for the virtual environment
being processed. creation request being processed.
""" """
url = 'https://raw.github.com/pypa/pip/master/contrib/get-pip.py' url = 'https://raw.github.com/pypa/pip/master/contrib/get-pip.py'
self.install_script(context, 'pip', url) self.install_script(context, 'pip', url)
@ -374,7 +380,8 @@ subclass which installs setuptools and pip into a created venv::
'more target ' 'more target '
'directories.') 'directories.')
parser.add_argument('dirs', metavar='ENV_DIR', nargs='+', 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, parser.add_argument('--no-setuptools', default=False,
action='store_true', dest='nodist', action='store_true', dest='nodist',
help="Don't install setuptools or pip in the " help="Don't install setuptools or pip in the "
@ -398,14 +405,17 @@ subclass which installs setuptools and pip into a created venv::
'the platform.') 'the platform.')
parser.add_argument('--clear', default=False, action='store_true', parser.add_argument('--clear', default=False, action='store_true',
dest='clear', help='Delete the contents of the ' dest='clear', help='Delete the contents of the '
'environment directory if it ' 'virtual environment '
'already exists, before ' 'directory if it already '
'exists, before virtual '
'environment creation.') 'environment creation.')
parser.add_argument('--upgrade', default=False, action='store_true', parser.add_argument('--upgrade', default=False, action='store_true',
dest='upgrade', help='Upgrade the environment ' dest='upgrade', help='Upgrade the virtual '
'directory to use this version ' 'environment directory to '
'of Python, assuming Python ' 'use this version of '
'has been upgraded in-place.') 'Python, assuming Python '
'has been upgraded '
'in-place.')
parser.add_argument('--verbose', default=False, action='store_true', parser.add_argument('--verbose', default=False, action='store_true',
dest='verbose', help='Display the output ' dest='verbose', help='Display the output '
'from the scripts which ' 'from the scripts which '

111
Doc/tutorial/venv.rst
View File

@ -20,15 +20,14 @@ the requirements of every application. If application A needs version
the requirements are in conflict and installing either version 1.0 or 2.0 the requirements are in conflict and installing either version 1.0 or 2.0
will leave one application unable to run. will leave one application unable to run.
The solution for this problem is to create a :term:`virtual The solution for this problem is to create a :term:`virtual environment`, a
environment` (often shortened to "virtualenv"), a self-contained self-contained directory tree that contains a Python installation for a
directory tree that contains a Python installation for a particular particular version of Python, plus a number of additional packages.
version of Python, plus a number of additional packages.
Different applications can then use different virtual environments. Different applications can then use different virtual environments.
To resolve the earlier example of conflicting requirements, To resolve the earlier example of conflicting requirements,
application A can have its own virtual environment with version 1.0 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 If application B requires a library be upgraded to version 3.0, this will
not affect application A's environment. not affect application A's environment.
@ -36,29 +35,26 @@ not affect application A's environment.
Creating Virtual Environments Creating Virtual Environments
============================= =============================
The script used to create and manage virtual environments is called The module used to create and manage virtual environments is called
:program:`pyvenv`. :program:`pyvenv` will usually install the most :mod:`venv`. :mod:`venv` will usually install the most recent version of
recent version of Python that you have available; the script is also Python that you have available. If you have multiple versions of Python on your
installed with a version number, so if you have multiple versions of system, you can select a specific Python version by running ``python3`` or
Python on your system you can select a specific Python version by whichever version you want.
running ``pyvenv-3.4`` or whichever version you want.
To create a virtualenv, decide upon a directory To create a virtual environment, decide upon a directory where you want to
where you want to place it and run :program:`pyvenv` with the place it, and run the :mod:`venv` module as a script with the directory path::
directory path::
pyvenv tutorial-env python3 -m venv tutorial-env
This will create the ``tutorial-env`` directory if it doesn't exist, This will create the ``tutorial-env`` directory if it doesn't exist,
and also create directories inside it containing a copy of the Python and also create directories inside it containing a copy of the Python
interpreter, the standard library, and various supporting files. interpreter, the standard library, and various supporting files.
Once you've created a virtual environment, you need to Once you've created a virtual environment, you may activate it.
activate it.
On Windows, run:: On Windows, run::
tutorial-env/Scripts/activate tutorial-env\Scripts\activate.bat
On Unix or MacOS, run:: On Unix or MacOS, run::
@ -69,33 +65,36 @@ On Unix or MacOS, run::
``activate.csh`` and ``activate.fish`` scripts you should use ``activate.csh`` and ``activate.fish`` scripts you should use
instead.) instead.)
Activating the virtualenv will change your shell's prompt to show what Activating the virtual environment will change your shell's prompt to show what
virtualenv you're using, and modify the environment so that running virtual environment you're using, and modify the environment so that running
``python`` will get you that particular version and installation of ``python`` will get you that particular version and installation of Python.
Python. For example:: For example:
-> source ~/envs/tutorial-env/bin/activate .. code-block:: bash
(tutorial-env) -> python
Python 3.4.3+ (3.4:c7b9645a6f35+, May 22 2015, 09:31:25) $ source ~/envs/tutorial-env/bin/activate
(tutorial-env) $ python
Python 3.5.1 (default, May 6 2016, 10:59:36)
... ...
>>> import sys >>> import sys
>>> sys.path >>> sys.path
['', '/usr/local/lib/python34.zip', ..., ['', '/usr/local/lib/python35.zip', ...,
'~/envs/tutorial-env/lib/python3.4/site-packages'] '~/envs/tutorial-env/lib/python3.5/site-packages']
>>> >>>
Managing Packages with pip Managing Packages with pip
========================== ==========================
Once you've activated a virtual environment, you can install, upgrade, You can install, upgrade, and remove packages using a program called
and remove packages using a program called :program:`pip`. By default :program:`pip`. By default ``pip`` will install packages from the Python
``pip`` will install packages from the Python Package Index, Package Index, <https://pypi.python.org/pypi>. You can browse the Python
<https://pypi.python.org/pypi>. You can browse the Python Package Index Package Index by going to it in your web browser, or you can use ``pip``'s
by going to it in your web browser, or you can use ``pip``'s limited search feature:
limited search feature::
(tutorial-env) -> pip search astronomy .. code-block:: bash
(tutorial-env) $ pip search astronomy
skyfield - Elegant astronomy for Python skyfield - Elegant astronomy for Python
gary - Galactic astronomy and gravitational dynamics. gary - Galactic astronomy and gravitational dynamics.
novas - The United States Naval Observatory NOVAS astronomy library novas - The United States Naval Observatory NOVAS astronomy library
@ -107,9 +106,11 @@ limited search feature::
"freeze", etc. (Consult the :ref:`installing-index` guide for "freeze", etc. (Consult the :ref:`installing-index` guide for
complete documentation for ``pip``.) 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 Collecting novas
Downloading novas-3.1.1.3.tar.gz (136kB) Downloading novas-3.1.1.3.tar.gz (136kB)
Installing collected packages: novas Installing collected packages: novas
@ -117,9 +118,11 @@ You can install the latest version of a package by specifying a package's name::
Successfully installed novas-3.1.1.3 Successfully installed novas-3.1.1.3
You can also install a specific version of a package by giving the 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 Collecting requests==2.6.0
Using cached requests-2.6.0-py2.py3-none-any.whl Using cached requests-2.6.0-py2.py3-none-any.whl
Installing collected packages: requests Installing collected packages: requests
@ -128,9 +131,11 @@ package name followed by ``==`` and the version number::
If you re-run this command, ``pip`` will notice that the requested If you re-run this command, ``pip`` will notice that the requested
version is already installed and do nothing. You can supply a version is already installed and do nothing. You can supply a
different version number to get that version, or you can run ``pip 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 Collecting requests
Installing collected packages: requests Installing collected packages: requests
Found existing installation: requests 2.6.0 Found existing installation: requests 2.6.0
@ -141,9 +146,11 @@ install --upgrade`` to upgrade the package to the latest version::
``pip uninstall`` followed by one or more package names will remove the ``pip uninstall`` followed by one or more package names will remove the
packages from the virtual environment. 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 Metadata-Version: 2.0
Name: requests Name: requests
@ -157,9 +164,11 @@ packages from the virtual environment.
Requires: Requires:
``pip list`` will display all of the packages installed in the virtual ``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) novas (3.1.1.3)
numpy (1.9.2) numpy (1.9.2)
pip (7.0.3) pip (7.0.3)
@ -168,19 +177,23 @@ environment::
``pip freeze`` will produce a similar list of the installed packages, ``pip freeze`` will produce a similar list of the installed packages,
but the output uses the format that ``pip install`` expects. 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 .. code-block:: bash
(tutorial-env) -> cat requirements.txt
(tutorial-env) $ pip freeze > requirements.txt
(tutorial-env) $ cat requirements.txt
novas==3.1.1.3 novas==3.1.1.3
numpy==1.9.2 numpy==1.9.2
requests==2.7.0 requests==2.7.0
The ``requirements.txt`` can then be committed to version control and The ``requirements.txt`` can then be committed to version control and
shipped as part of an application. Users can then install all the 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 novas==3.1.1.3 (from -r requirements.txt (line 1))
... ...
Collecting numpy==1.9.2 (from -r requirements.txt (line 2)) Collecting numpy==1.9.2 (from -r requirements.txt (line 2))

1
Doc/using/index.rst
View File

@ -17,4 +17,3 @@ interpreter and things that make working with Python easier.
unix.rst unix.rst
windows.rst windows.rst
mac.rst mac.rst
scripts.rst

12
Doc/using/scripts.rst
View File

@ -1,12 +0,0 @@
.. _tools-and-scripts:
Additional Tools and Scripts
============================
.. _scripts-pyvenv:
pyvenv - Creating virtual environments
--------------------------------------
.. include:: venv-create.inc

91
Doc/using/venv-create.inc
View File

@ -1,31 +1,39 @@
Creation of :ref:`virtual environments <venv-def>` is done by executing the 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 Running this command creates the target directory (creating any parent
directories that don't exist already) and places a ``pyvenv.cfg`` file in it 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 with a ``home`` key pointing to the Python installation from which the command
from. It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory 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 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`` Windows). It also creates an (initially empty) ``lib/pythonX.Y/site-packages``
subdirectory (on Windows, this is ``Lib\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:: .. seealso::
`Python Packaging User Guide: Creating and using virtual environments `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 .. highlight:: none
On Windows, you may have to invoke the ``pyvenv`` script as follows, if you On Windows, invoke the ``venv`` command as follows::
don't have the relevant PATH and PATHEXT settings::
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:: 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. Creates virtual Python environments in one or more target directories.
positional arguments: positional arguments:
ENV_DIR A directory to create the environment in. ENV_DIR A directory to create the environment in.
optional arguments: optional arguments:
-h, --help show this help message and exit -h, --help show this help message and exit
--system-site-packages Give the virtual environment access to the system --system-site-packages
site-packages dir. Give the virtual environment access to the system
--symlinks Try to use symlinks rather than copies, when symlinks site-packages dir.
are not the default for the platform. --symlinks Try to use symlinks rather than copies, when symlinks
--copies Try to use copies rather than symlinks, even when are not the default for the platform.
symlinks are the default for the platform. --copies Try to use copies rather than symlinks, even when
--clear Delete the contents of the environment directory if it symlinks are the default for the platform.
already exists, before environment creation. --clear Delete the contents of the environment directory if it
--upgrade Upgrade the environment directory to use this version already exists, before environment creation.
of Python, assuming Python has been upgraded in-place. --upgrade Upgrade the environment directory to use this version
--without-pip Skips installing or upgrading pip in the virtual of Python, assuming Python has been upgraded in-place.
environment (pip is bootstrapped by default) --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 Once an environment has been created, you may wish to activate it, e.g. by
may vary slightly, e.g. referencing ``pyvenv`` rather than ``venv``. sourcing an activate script in its bin directory.
.. versionchanged:: 3.4 .. versionchanged:: 3.4
Installs pip by default, added the ``--without-pip`` and ``--copies`` 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 Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be
invoked to bootstrap ``pip`` into the virtual environment. invoked to bootstrap ``pip`` into the virtual environment.
Multiple paths can be given to ``pyvenv``, in which case an identical Multiple paths can be given to ``venv``, in which case an identical virtual
virtualenv will be created, according to the given options, at each environment will be created, according to the given options, at each provided
provided path. path.
Once a venv has been created, it can be "activated" using a script in the Once a virtual environment has been created, it can be "activated" using a
venv's binary directory. The invocation of the script is platform-specific: script in the virtual environment's binary directory. The invocation of the
script is platform-specific:
+-------------+-----------------+-----------------------------------------+ +-------------+-----------------+-----------------------------------------+
| Platform | Shell | Command to activate virtual environment | | 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 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 prepends the virtual environment's binary directory to your path, so that
venv's Python interpreter and you can run installed scripts without having to "python" invokes the virtual environment's Python interpreter and you can run
use their full path. However, all scripts installed in a venv should be installed scripts without having to use their full path. However, all scripts
runnable without activating it, and run with the venv's Python automatically. 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 You can deactivate a virtual environment by typing "deactivate" in your shell.
mechanism is platform-specific: for example, the Bash activation script defines The exact mechanism is platform-specific: for example, the Bash activation
a "deactivate" function, whereas on Windows there are separate scripts called script defines a "deactivate" function, whereas on Windows there are separate
``deactivate.bat`` and ``Deactivate.ps1`` which are installed when the venv is scripts called ``deactivate.bat`` and ``Deactivate.ps1`` which are installed
created. when the virtual environment is created.
.. versionadded:: 3.4 .. versionadded:: 3.4
``fish`` and ``csh`` activation scripts. ``fish`` and ``csh`` activation scripts.

1
Misc/ACKS
View File

@ -1150,6 +1150,7 @@ Dusty Phillips
Christopher J. Phoenix Christopher J. Phoenix
James Pickering James Pickering
Neale Pickett Neale Pickett
Steve Piercy
Jim St. Pierre Jim St. Pierre
Dan Pierson Dan Pierson
Martijn Pieters Martijn Pieters

6
Misc/NEWS
View File

@ -154,6 +154,12 @@ Tools/Demos
- Issue #27418: Fixed Tools/importbench/importbench.py. - Issue #27418: Fixed Tools/importbench/importbench.py.
Documentation
-------------
- Issue #27285: Update documentation to reflect the deprecation of ``pyvenv``
and normalize on the term "virtual environment". Patch by Steve Piercy.
What's New in Python 3.6.0 alpha 2 What's New in Python 3.6.0 alpha 2
================================== ==================================