- replace `pyvenv` with `python3 -m venv`

4 files changed, 25 insertions, 25 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index 1d8e0de1b..fd32ed796 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -1100,10 +1100,16 @@ Glossary
       checker, and applying a renderer to a dictionary returned from the view.
 
    pip
-      The `Python Packaging Authority <https://www.pypa.io/>`_ recommended tool
-      for installing Python packages.
+      The `Python Packaging Authority's <https://www.pypa.io/>`_ recommended
+      tool for installing Python packages.
 
    pyvenv
-      The Python Packaging Authority's recommended command for `creating
-      virtual environments on Python 3.4 and greater
-      <https://packaging.python.org/en/latest/installing/#creating-virtual-environments>`_.
+      The Python Packaging Authority formerly recommended using this command
+      for `creating virtual environments on Python 3.4 and 3.5
+      <https://packaging.python.org/en/latest/installing/#creating-virtual-environments>`_,
+      but it is deprecated in 3.6 in favor of ``python3 -m venv`` which is
+      backward compatible.
+
+   venv
+      The `Python Packaging Authority's <https://www.pypa.io/>`_ recommended
+      tool for creating virtual environments.
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index febdc87cc..548d040f1 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -126,8 +126,8 @@ also need to download and install the Python for Windows extensions.
 Requirements for Installing Packages
 ------------------------------------
 
-Use :term:`pip` for installing packages and :term:`pyvenv` for creating a
-virtual environment. A virtual environment is a semi-isolated Python
+Use :term:`pip` for installing packages and ``python3 -m venv env`` for
+creating a virtual environment. 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.
 
@@ -155,7 +155,7 @@ After installing Python as described previously in :ref:`for-mac-os-x-users` or
    .. code-block:: bash
 
       $ export VENV=~/env
-      $ pyvenv $VENV
+      $ python3 -m venv $VENV
 
    You can either follow the use of the environment variable ``$VENV``, or
    replace it with the root directory of the virtual environment. If you choose
@@ -190,7 +190,7 @@ After installing Python as described previously in
 
       c:\> set VENV=c:\env
       # replace "x" with your minor version of Python 3
-      c:\> c:\Python3x\Scripts\pyvenv %VENV%
+      c:\> c:\Python3x\Scripts\python3 -m venv %VENV%
 
    You can either follow the use of the environment variable ``%VENV%``, or
    replace it with the root directory of the virtual environment. If you choose
diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst
index f1cec97e9..04b70bcd1 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -25,7 +25,7 @@ As an example, for Python 3.5+ on Linux:
 
 .. parsed-literal::
 
-    $ pyvenv env
+    $ python3 -m venv env
     $ env/bin/pip install pyramid
     # or for a specific released version
     $ env/bin/pip install "pyramid==\ |release|\ "
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst
index c4e6beecb..17ce845e2 100644
--- a/docs/quick_tutorial/requirements.rst
+++ b/docs/quick_tutorial/requirements.rst
@@ -22,9 +22,9 @@ This *Quick Tutorial* is based on:
 * **Python 3.5**. Pyramid fully supports Python 3.3+ and Python 2.6+. This
   tutorial uses **Python 3.5** but runs fine under Python 2.7.
 
-* **pyvenv**. We believe in virtual environments. For this tutorial, we use
-  Python 3.5's built-in solution, the ``pyvenv`` command. For Python 2.7, you
-  can install ``virtualenv``.
+* **venv**. We believe in virtual environments. For this tutorial, we use
+  Python 3.5's built-in solution ``venv``. For Python 2.7, you can install
+  ``virtualenv``.
 
 * **pip**. We use ``pip`` for package management.
 
@@ -158,26 +158,20 @@ environment. We set an environment variable to save typing later.
 Create a Virtual Environment
 ----------------------------
 
-.. warning:: The current state of isolated Python environments using
-    ``pyvenv`` on Windows is suboptimal in comparison to Mac and Linux.  See
-    http://stackoverflow.com/q/15981111/95735 for a discussion of the issue
-    and `PEP 453 <http://www.python.org/dev/peps/pep-0453/>`_ for a proposed
-    resolution.
-
-``pyvenv`` is a tool to create isolated Python 3 environments, each
-with its own Python binary and independent set of installed Python
-packages in its site directories. Let's create one, using the location
-we just specified in the environment variable.
+``venv`` is a tool to create isolated Python 3 environments, each with its own
+Python binary and independent set of installed Python packages in its site
+directories. Let's create one, using the location we just specified in the
+environment variable.
 
 .. code-block:: bash
 
     # Mac and Linux
-    $ pyvenv $VENV
+    $ python3 -m venv $VENV
 
 .. code-block:: ps1con
 
     # Windows
-    c:\> c:\Python35\python -m venv %VENV%
+    c:\> c:\Python35\python3 -m venv %VENV%
 
 .. seealso:: See also Python 3's :mod:`venv module <python:venv>` and Python
    2's `virtualenv <http://www.virtualenv.org/en/latest/>`_ package.