Slides will be posted on my blog at

Using virtualenv

"virtualenv is a tool to create isolated Python environments."

First released in 2007, replaced earlier attempt workingenv with ideas from PEAK's

Written by Ian Bicking


Not this

What is a Python Development Environment?


Image by

How Stuff Works

Something Simple Like

$ python
>>>import foo

Not so simple


The rest is up to the "site" module: auto-imported and searches $PYTHONPATH, site-packages, .pth files

Or your code can manually add paths to sys.path (this way lies madness).

Why do we need this stuff?

Your application code lives in "."

App x requires module foo 1.0 and python 2.5, app y requires module foo 0.9 and python 2.4

Usual Python Tools

Handling 3rd party libraries is usually done with distutils or setuptools (easy_install).

$ cd foo1.2.3
$ sudo python install
  ... or ...
$ sudo easy_install foo

By default installs everything to system wide site-packages. Has some tools for handling conflict (--home=~/alt-site-packages) but mostly doesn't set policy and expects you to roll your own environments to manage potential conflicts.

No Magic

Virtualenv is just a set of tools to manage your environment in a cohesive organised way. Everything it does you could replicate with judicious use of environmental variables, installation prefixes, full paths to binaries, etc etc.

But why bother!

(And who wants to mess with this stuff on windows?)


$ cd /tmp
$ virtualenv ./pyenv
New python executable in pyenv/bin/python
Installing setuptools............done.
$ ls pyenv
bin include lib
$ source ./pyenv/bin/activate
(pyenv)$ easy_install simplejson
(pyenv)$ ls  pyenv/lib/python2.5/site-packages/
easy-install.pth  ...snip...  simplejson-2.0.9-py2.5.egg
(pyenv)$ deactivate

That seems simple

Yes it is. Simple is good. I use virtual env to:

Use an env when starting a new project. If nothing else it helps you keep track of dependencies (what python packages did I install for this project).

Use an env to test out random libraries

Make an env in /tmp. easy_install half a dozen packages you aren't likely to keep around - and delete the env when you're done (and your shared site-packages directory stays clean).

Make an env for different requirements - one for python 2.4 (use the -p option to specify the python executable) with extra libraries, one for 2.5, one for 2.6. Activate each one and run your test suite.

Advanced Usage & Gotchas

Use with other tools that directly support virtualenv (mod_wsgi, pip)

By default an env has access to the system-wide site-packages directory. To get really pristine you can use --no-site-packages option.

There are hooks that allow you to easily create a script that runs after env creation. Distribute your script to easily replicate your development environment.

Global binaries (not installed in virtualenv) may not respect your env. Running ipython in an activated virtual environment won't do what you want unless you have installed it in the env.

The End