Virtualenv is a tool to build isolated Python environments. It's a great way to quickly test new libraries without cluttering your global site-packages or run multiple projects on the same machine which depend on a particular library but not the same version of the library.
You can, for example, install version X of a library in one environment and version Z of the same library in another environment, without one interfering the other. Each environment provides its own Python executable and site-packages directory (which is not shared between environments).
$ easy_install virtualenv
$ virtualenv venv
$ source venv/bin/activate
$ easy_install yolk
$ pip install django=1.3
$ pip install -E venv/ -r venv/requirements.txt
$ export PIP_RESPECT_VIRTUALENV=true
To install virtualenv, simply easy_install it with the following command:
$ easy_install virtualenv
Once virtualenv is installed, you can use the virtualenv command to create virtual environments.
The following command will create an environment called "venv":
$ virtualenv venv
You can activate the environment by sourcing its activate script, which is located in the environment's bin/ directory:
$ source venv/bin/activate
or with the following shortcut
$ . venv/bin/activate
The script prepends the name of the currently activated environment to the $PS1 of your shell and sets the environment's site-packages directory as the default one.
If you install a package in your virtual environment, you'll see that executable scripts are placed in foobar/bin/ and eggs in foobar/lib/python2.X/site-packages/:
$ easy_install yolk
Yolk is a small command line tool which can, among other things, list the currently installed Python packages on your system:
$ yolk -l
As you see, virtualenv will inherit the packages from the system's default site-packages directory. This is especially useful when relying on certain packages being available, so you don't have to go through installing them in every environment.
It is best to try to keep your system's site-packages directory fairly minimal and only put packages there which I use in nearly every project. Good examples are things like database interfaces such as MySQLdb or psycopg2 as well as setuptools and, of course, virtualenv. If you are running Linux you will probably want to use apt-get to install these applications. For Mac users, Brew is a nice clone of apt-get that is worth a look.
However, you can also change this by passing the --no-site-packages option to virtualenv when creating a virtual environment. This will create a clean environment without inheriting the packages from your global site-packages directory:
$ virtualenv --no-site-packages cleanvenv
To leave an environment, simply run deactivate:
$ deactivate
Try executing the yolk command now: it won't work because the package was installed only in your virtual environment. Once you reactivate your environment it will be available again.
Now create a new file requirements.txt and save it in your venv/ directory with the requirements per [TODO instructions]
$ pip install -E venv/ -r venv/requirements.txt
Note: You needed to pass in the "-E" switch to pip to signify that you want the packages installed in a certain virtualenv:
Additionally, there are several environment variables you can set to alter the way pip behaves. To get pip to always use the currently active virtualenv, use:
$ export PIP_RESPECT_VIRTUALENV=true