Utilizing virtualenv

Different projects, applications, or scripts may require different versions of Python (e.g. 2.6 vs 2.7 vs 3.X) and can have different sets of dependencies. Virtual environments are a great way of creating isolated spaces for compartmentalizing specific Python versions and/or sets of package dependencies for separate projects and applications.

This additionally prevents the global Python installs from becoming polluted with a plethora of packages and incompatibilities between applications which may require different versions of the same dependency that may lead to conflicts or difficult-to-debug errors. It also avoids typical permissions errors when managing global packages and makes removing a set of application dependencies as simple as deleting the virtualenv directory.

NOTE: While the prerequisites recommend the latest Python 2 and Python 3 installs, if there is a situation where you need a very specific version of Python, as long as that version is installed and you know the path to the Python executable then you can create a virtual environment for that version.

Prerequisites

  • First things first, make sure that you have the latest version of Python 2 or Python 3 downloaded and installed (or just skip the manual download by installing via the appropriate package manager for your OS)

  • Next you’ll need to make sure that pip is installed (it comes automatically with Python 2 >= 2.7.9 and Python 3 >= 3.4)

  • Ensure that pip and setuptools are updated: pip install -U pip setuptools

Setup

Next we’ll need to install the virtual environment packages:

pip install -U virtualenvwrapper virtualenv

WINDOWS: if you are doing this on a windows box you will instead need to install virtualenvwrapper-win and follow the directions here (good luck!):

pip install -U virtualenvwrapper-win virtualenv

While virtualenv can be used by itself, it is far easier to use the wrapper package which makes creating, managing, and activating virtual environments a far more pleasant experience.

Configuration

WINDOWS: again, if you are doing this on a windows box, you should refer to these directions since virtualenvwrapper, and hence this whole section, is only for Bourne-compatible shells (have fun!)

Now that everything is installed, we need to configure our environment to actually utilize it. The following needs to be added somewhere in your ~/.bash_profile or your shell equivalent file:

#######################################################
### virtualenv setup and shortcuts
export PIP_REQUIRE_VIRTUALENV=true
export WORKON_HOME="~/.envs"
if [ -f /usr/local/bin/virtualenvwrapper.sh ]; then
  source /usr/local/bin/virtualenvwrapper.sh;
fi
alias mkvenv="mkvirtualenv"
alias mkvenv3="mkvirtualenv -p python3"
alias rmvenv="rmvirtualenv"
alias lsvenv="lsvirtualenv"

Broken down, the export PIP_REQUIRE_VIRTUALENV=true actually prevents Python packages from being installed globally unless a specific flag is passed to pip to force it install anyway. What this does is it reminds you if you forget to activate a virtual env, and prevents packages from being installed globally unless you specifically go out of your way to do so.

The export WORKON_HOME="~/.envs" tells virtualenvwrapper the location where you want it to create all of your virtual environments (this should NOT be within a git repository as the env should NOT be committed with code). Modify this export as needed for wherever you want it to use as the location.

The if statement is actually the most important part of the additions since it is what actually initializes the wrapper whenever you start a shell session so it can do its job. Without the wrapper script getting sourced, it will not work correctly!

The remainder of the additions are aliases which I like to use, however they are not strictly required if you do not wish to add them.

Managing envs

Basic usage for creating a virtual env is:

mkvirtualenv <env-name>

For example:

mkvirtualenv example

Or using the alias:

mkvenv example

You can similarly list or remove environments using the aliases:

lsvenv
rmvenv example

Creating a Python 3 env

The alias from above can be used to quickly create a virtual env with the system install version of Python 3:

mkvenv3 example_env

Or using just virtualenvwrapper without the alias:

mkvirtualenv -p python3 example_env

Using specific Python versions

To use a specific version of Python in a virtual env, you need to explicitly tell it which one via the -p flag:

mkvirtualenv -p path/to/specific/version/of/python
mkvenv -p path/to/specific/version/of/python

Activating/deactivating an env

When creating a virtual env, it will automatically be activated, however, to activate an env that is not currently active, you use the workon command:

workon example_env

Activating a virtual env gives you access to the installed packages in the env and the normal Python executable found on the command line should be the executable for the version of Python specified when the env was created (the default Python install on the system if none was specified). Deactivating an env

Leaving an env is also very simple:

deactivate