Setting up virtualenv
=====================

.. Contents::

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


.. include:: ../../links_names.txt

.. _Prabhu: http://prabhuramachandran.blogspot.com/2008/03/using-virtualenv-under-linux.html
.. _Gael: http://gael-varoquaux.info/blog/
.. _Jarrod: http://jarrodmillman.blogspot.com/
.. _Fernando: http://fdoperez.blogspot.com/search/label/scipy
.. _Scipy2008: http://conference.scipy.org/
.. _prerequisites: https://svn.enthought.com/enthought/wiki/Install
