# Setting up virtualenv

## Overview

virtualenv is a tool that allows you to install python packages in isolated environments. In this way you can have multiple versions of the same package without interference. I started using this to easily switch between multiple versions of numpy without having to constantly reinstall and update my symlinks. I also did this as a way to install software for Scipy2008, like the Enthought Tool Suite (ETS), in a way that would not effect my current development environment.

This tutorial is based heavily on a blog entry from Prabhu. I’ve extended his shell script to make switching between virtual environments a one-command operation. (Few others who should be credited for encouraging me to use virtualenv: Gael, Jarrod, Fernando)

## Installing

Download and install the tarball for virtualenv:

    tar xzf virtualenv-1.1.tar.gz
    cd virtualenv-1.1
    python setup.py install --prefix=$HOME/local

Note: I install in a local directory, your install location may differ.

## Setup virtualenv

Setup a base virtualenv directory. I create this in a local directory, you can do this in a place of your choosing. All virtual environments will be installed as subdirectories in here.:

    cd ~/local
    mkdir -p virtualenv

## Create a virtualenv

Create a virtual environment. Here I change into my virtualenv directory and create a virtual environment for my numpy-1.1.1 install:

    cd virtualenv/
    virtualenv numpy-1.1.1

## Activate a virtualenv

Set the numpy-1.1.1 as the active virtual environment:

    ln -s numpy-1.1.1/bin/activate .

We enable the numpy-1.1.1 virtual environment by sourcing it’s activate script. This will prepend our PATH with the currently active virtual environment.:

    # note: still in the ~/local/virtualenv directory
    source activate

We can see our PATH with the numpy-1.1.1 virtual environment at the beginning. Also not the label of the virtual environment prepends our prompt.:

    (numpy-1.1.1)cburns@~ 20:23:54 $ echo $PATH
    /Users/cburns/local/virtualenv/numpy-1.1.1/bin:
    /Library/Frameworks/Python.framework/Versions/Current/bin:
    /Users/cburns/local/bin:
    /usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/usr/X11/bin:/usr/local/git/bin

## Install packages into a virtualenv

Then we install numpy-1.1.1 into the virtual environment. In order to install packages in the virtual environment, you need to use the python or easy_install from that virtualenv.:

    ~/local/virtualenv/numpy-1.1.1/bin/python setup.py install

At this point any package I install in this virtual environment will only be used when the environment is active.

## Pragmatic virtualenv

There are a few more manual steps in the above process then I wanted, so I extended the shell script that Prabhu wrote to make this a simple one-command operation. One still needs to manually create each virtual environment, and install packages, but this script simplifies activating and deactivating them.

The venv_switch.sh script will:

- Activate the selected virtual environment. (Or issue an error if it doesn’t exist.)

- Launch a new bash shell using the ~/.virtualenvrc file which sources the virtualenv/activate script.

- The activate script modifies the PATH and prepends the bash prompt with the virtualenv label.

venv_switch.sh:

    #!/bin/sh
    # venv_switch.sh
    # switch between different virtual environments

    # verify a virtualenv is passed in
    if [ $# -ne 1 ]
    then
        echo 'Usage: venv_switch venv-label'
        exit -1
    fi

    # verify the virtualenv exists
    VENV_PATH=~/local/virtualenv/$1

    # activate env script
    ACTIVATE_ENV=~/local/virtualenv/activate

    echo $VENV_PATH
    if [ -e $VENV_PATH ]
    then
        echo 'Switching to virtualenv' $VENV_PATH
        echo "Starting new bash shell.  Simply 'exit' to return to previous shell"
    else
        echo 'Error: virtualenv' $VENV_PATH 'does not exist!'
        exit -1
    fi

    rm $ACTIVATE_ENV
    ln -s ~/local/virtualenv/$1/bin/activate $ACTIVATE_ENV

    # Launch new terminal
    bash --rcfile ~/.virtualenvrc

Now to activate our numpy-1.1.1 virtual environment, we simply do:

    venv_switch.sh numpy-1.1.1

To deactivate the virtual environment and go back to your original environment, just exit the bash shell:

    exit

The rcfile used to source the activate script. I first source my .profile to setup my environment and custom prompt, then source the virtual environment. .virtualenvrc:

    # rc file to initialize bash environment for virtualenv sessions

    # first source the bash_profile
    source ~/.bash_profile

    # source the virtualenv
    source ~/local/virtualenv/activate

## Installing ETS 3.0.0

As another example, I installed ETS 3.0.0 for the Tutorial sessions at Scipy2008. (Note the prerequisites.)

Set up an ets-3.0.0 virtualenv:

    cburns@virtualenv 15:23:50 $ pwd
    /Users/cburns/local/virtualenv

    cburns@virtualenv 15:23:50 $ virtualenv ets-3.0.0
    New python executable in ets-3.0.0/bin/python
    Installing setuptools............done.

    cburns@virtualenv 15:24:29 $ ls
    activate      ets-3.0.0       numpy-1.1.1     numpy-1.2.0b2

Switch into my ets-3.0.0 virtualenv using the venv_switch.sh script:

    cburns@~ 15:29:12 $ venv_switch.sh ets-3.0.0
    /Users/cburns/local/virtualenv/ets-3.0.0
    Switching to virtualenv /Users/cburns/local/virtualenv/ets-3.0.0
    Starting new bash shell.  Simply 'exit' to return to previous shell

Install ETS using easy_install. Note we need to use the easy_install from our ets-3.0.0 virtual environment:

    (ets-3.0.0)cburns@~ 15:31:41 $ which easy_install
    /Users/cburns/local/virtualenv/ets-3.0.0/bin/easy_install

    (ets-3.0.0)cburns@~ 15:31:48 $ easy_install ETS