5.1. pyvenv - Creating virtual environments¶

Creation ofvirtual environments is done by executing thepyvenv script:

pyvenv/path/to/new/virtual/environment

Running this command creates the target directory (creating any parentdirectories that don’t exist already) and places apyvenv.cfg file in itwith ahome key pointing to the Python installation the command was runfrom. It also creates abin (orScripts on Windows) subdirectorycontaining a copy of thepython binary (or binaries, in the case ofWindows). It also creates an (initially empty)lib/pythonX.Y/site-packagessubdirectory (on Windows, this isLib\site-packages).

On Windows, you may have to invoke thepyvenv script as follows, if youdon’t have the relevant PATH and PATHEXT settings:

c:\Temp>c:\Python35\python c:\Python35\Tools\Scripts\pyvenv.py myenv

or equivalently:

c:\Temp>c:\Python35\python -m venv myenv

The command, if run with-h, will show the available options:

usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]            [--upgrade] [--without-pip]            ENV_DIR [ENV_DIR ...]Creates virtual Python environments in one or more target directories.positional arguments:  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 thevenv functionality has been invoked, the usage messagemay vary slightly, e.g. referencingpyvenv rather thanvenv.

The createdpyvenv.cfg file also includes theinclude-system-site-packages key, set totrue ifvenv isrun with the--system-site-packages option,false otherwise.

Unless the--without-pip option is given,ensurepip will beinvoked to bootstrappip into the virtual environment.

Multiple paths can be given topyvenv, in which case an identicalvirtualenv will be created, according to the given options, at eachprovided path.

Once a venv has been created, it can be “activated” using a script in thevenv’s binary directory. The invocation of the script is platform-specific:

You don’t specificallyneed to activate an environment; activation justprepends the venv’s binary directory to your path, so that “python” invokes thevenv’s Python interpreter and you can run installed scripts without having touse their full path. However, all scripts installed in a venv should berunnable without activating it, and run with the venv’s Python automatically.

You can deactivate a venv by typing “deactivate” in your shell. The exactmechanism is platform-specific: for example, the Bash activation script definesa “deactivate” function, whereas on Windows there are separate scripts calleddeactivate.bat andDeactivate.ps1 which are installed when the venv iscreated.