Setting up virtualenv


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)


Download and install the tarball for virtualenv:

tar xzf virtualenv-1.1.tar.gz
cd virtualenv-1.1
python 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

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 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 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.

# switch between different virtual environments

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

# verify the virtualenv exists

# activate env script

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

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: numpy-1.1.1

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


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

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 script:

cburns@~ 15:29:12 $ 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

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