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:\Python33\python c:\Python33\Tools\Scripts\pyvenv.py myenv

or equivalently:

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

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

usage: pyvenv [-h] [--system-site-packages] [--symlinks] [--clear]              [--upgrade] 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 access to the global site-packages dir to the                         virtual environment.  --symlinks             Try to use symlinks rather than copies, when symlinks                         are not the default for the platform.  --clear                Delete the environment directory if it already exists.                         If not specified and the directory exists, an error is                         raised.  --upgrade              Upgrade the environment directory to use this version                         of Python, assuming Python has been upgraded in-place.

If the target directory already exists an error will be raised, unlessthe--clear or--upgrade option was provided.

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

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: ona Posix platform, you would typically do:

$ source <venv>/bin/activate

whereas on Windows, you might do:

C:\> <venv>/Scripts/activate

if you are using thecmd.exe shell, or perhaps:

PS C:\> <venv>/Scripts/Activate.ps1

if you use PowerShell.

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.