Skip to content

Instantly share code, notes, and snippets.

@alokm
Created February 4, 2012 02:50
Show Gist options
  • Save alokm/1734708 to your computer and use it in GitHub Desktop.
Save alokm/1734708 to your computer and use it in GitHub Desktop.
A Gentle Introduction to Python Library Management with Virtualenv

Introduction

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

Quickstart Command Sampler

$ 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

Installation

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.

Tutorial

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.

Advanced

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment