So this is going to be something that comes up in a couple places: in the general case, we should refer to "virtual environments" and only refer to "virtualenv" for Python 2 users and "venv" (and pyvenv) for Python 3 users. They both create virtual environments, but the tools have different names.

FWIW virtualenv still works on Python 3 and it's likely folks might still want to use that over pyvenv. Reasoning:

• pyvenv only exists in 3.3+, so if you want to use 3.2 you're stuck.
• pyvenv only installs pip in 3.4+, so if you want to use 3.3 you have to get your own pip.
• pyvenv is tied to a specific version of Python, so you'll get different versions of pip (and thus different behavior from pip) depending on what version of Python you're using.
• pyvenv is tied to a specific version of Python, so you'll get different options, flags, etc available based on the Python version.

Longer term, virtualenv will be rewritten to take advantage of the isolation mechanism provided by pyvenv but still provide it's own pip and such to make it easier to have something creating a virtual environment with an up to date copy of the bundled tooling and that works the same across all versions of Python.

@dstufft Oh, those are some important distinctions (I didn't notice pyvenv wasn't in Python until 3.3)! In light of that, I'm tempted to say we should suggest virtualenv for all readers (Python 2 and 3 users alike), in the interest of having it Just Work. Is there a good reason not to use virtualenv on Python 3.3+?

Currently virtualenv doesn't take advantage of the better isolation mechanism introduced by pyvenv, it still uses the total black magic hack which can break sometimes (particularly on brand new versions of Python). Also it doesn't come with Python.

The first of those will hopefully be solved at some point in the future, the second of those will always be true.

At the moment, "use virtualenv" is probably the simplest "one solution suits everyone" advice. But I'm uncomfortable about not letting people know that Python 3 has a better native virtual environment facility. I suspect my discomfort merely reflects that I'm not a good person to write beginner-focused documentation, though :-)

OK, after sleeping on this one, I think we should go with "use virtualenv" for Python 2.7-3.2 users and "use pyvenv" for 3.3+. As much I'd like to go with a one-size fits all solution, I think there's something to be said for acknowledging that Python is changing thing. And if test readers say that doesn't work for them, then we can always change it.

Cool, thanks all for the comments, I will address them in my next update.

We want pip instead of pip3. If a virtualenv is actually activated, pip3 can't be better - and additionally, of course, running pip3 in a python 2 virtualenv will only get you wrong results.

This isn't true everywhere - on Windows at least, pyvenv is not on the path by default. I would suggest python -m venv as the canonical way of running pyvenv.