Virtual Environment

Indices and tables

Introduction

A virtual environment attempts to solve the following problems:

  • Avoid package version conflicts when multiple apps require different versions.
  • Let you add packages to the system if you aren’t root.

Virtual environments (or virtalenv, or venv) solve this problem by creating a standalone, self-contained directory that contains:

  • A copy of the required version of the Python interpreter
  • All the versions of the required packages needed to run the application.

Inside the virtual environment, you will find the following:

  • /bin - Contains the version of python interpreter and pip needed by your application. Also contains binaries to activate and de-active the virtual environment.
  • /lib/pythonX.Y/site-packages - Contains 3rd party packages, local to the venv (packages from the standard library still come from the directory of the requested version of Python).
  • pyvenv.cfg - A file that contains info about how the virtual environment was configured. However it is more useful in its role as a marker that the directory it is in belongs to a virtual environment (so settings like sys.prefix and sys.exec_prefix are set to point to the virtual environment before they are added to the module search path).

You can have multiple virtual environments and they will all be isolated from each other.

The specification for virtual environment support in Python is given in PEP 405.

Creating a Venv

The pyvenv program handles virtual environment creation.

To create a venv without any 3rd party packages, call pyvenv with the name of the venv to create. For example:

%> pyvenv testenv

You can create a venv and include all previously downloaded 3rd party packages already on the system, by using the --system-site-packages when invoking pyvenv. For example:

%> pyvenv --system-site-packages testenv

To create a venv with a specific Python version, call pyvenv-X.Y. For example, to create a venv that uses Python v3.5, execute the following:

%> pyvenv-3.5 testenv

Note

You must have the requested version of Python installed on your system,

There are a few additional options to pyvenv you can explore if you type pyvenv --help.

Using a Venv

The first step in using a venv is to “activate” it. Behind the scenes, the following changes occur when a venv is activated:

  • The environment variable PATH is set to have the venv/bin directory at the head of the PATH. This ensure the venv’s python interpreter is called and not the system’s.
  • The environment variable PYTHONHOME is unset, to remove any previously set paths that should be included in the module search path.
  • The environment variable VIRTUAL_ENV is set to point to the virtualenv directory.
  • Changes the shell prompt to include the name of the venv.

Activation is accomplished by sourcing the activation file in /bin. For example:

&> source testenv/bin/activate
(testenv) %>

Once the venv is activated:

  • Starting Python will start the interpreter version found in the venv.
  • Importing 3rd party packages in source code will reference the packages installed in the venv (however, standard library packages will still come from the usual system location where Python is installed).
  • Installing packages using pip will install them into the venv.

When you are done with the venv, you can deactivate it to return the prompt, PATH and module search path back to their pre-venv settings. To deactivate the venv, execute deactivate in your shell.

Destroying a Venv

Destroying a venv is as simple as deleting the directory that defines it.