# easy_install virtualenv virtualenvwrapper


Virtualenvwrapper is a set of shell scripts that offers command line tools for managing and using virtualenvs.

Install it by adding:

export WORKON_HOME=$HOME/.virtualenvs
source /usr/bin/

to ~/.bash_profile. Create the $WORKON_HOME directory:

mkdir $HOME/.virtualenvs

Mac OS X

On OS X, you'll need XCode installed to use mkvirtualenv.


Ensure that yolk is not installed system-wide. A central yolk will show the pacakge list for the sytem, not for the active virtualenv.

Using a virtualenv

Virtualenvs are defined by a restricted PYTHONPATH and a dedicated bin directory for scripts that run within the virtualenv.

A virtualenv can be used:

  • Through virtualenv wrapper, via the shell after using workon
  • By calling a python script using the python binary within the virtualenv's bin directory. Calling any python scripts installed by easy_install in that bin directory will automatically use this special python.
  • By setting the PYTHONPATH manually

With virtualenvwrapper

It's easiest to manage virtualenvs via virtualenv wrapper:

Virtualenvs are most useful if they do not include any packages installed globally on the system. This is accomplished by creating a new virtualenv with:

$ mkvirtualenv --no-site-packages mynewvirtualenv

This will activate the new virtualenv. To leave the virtualenv, deactivate it:

$ deactivate

To work on it again:

$ workon mynewvirtualenv

It's almost always useful to have yolk in each virtualenv:

$ easy_install yolk

Via the special python binaries

It's easiest to launch virtualenv-restricted Python daemons from scripts using the special python found in each virtualenv's bin directory:

$ /home/app/.virtualenvs/myve/bin/python

If your daemon is available as an executable Python script installed on the PATH, it will be available in the virtualenv's bin directory. Calling it directly will use the virtualenv's PYTHONPATH:

$ /home/app/.virtualenvs/myve/bin/foo

Creating virtualenvs without virtualenvwrapper

It's also possible to create virtualenvs with the bare virtualenv command. It takes the same --no-site-packages option as mkvirtualenv, but the argument passed to it is not the name of the new virtualenv within the virtualenv directory but insted a path where the new virtualenv should be installed. This allows for easy scripting of virtualevn creation.

$ virtualenv --no-site-packages /var/virtualenvs/myvirtualenv

Or, in a Makefile:

    virtualenv --no-site-packages $(VIRTUALENV_PATH)/$(PROJECT_NAME)