The virtualenv package is one of the most useful tools in any Python programmer's toolbox.

In short, it creates an isolated Python environment.

Why this is awesome:

  • Install different versions of Python packages such as Django.
  • Have a separate Python sandbox for each of your projects.
  • Doesn't require root to install or use pip or easy_install.
  • Easy to re-create using the pip freeze command.


Download virtualenv and extract it somewhere in your home directory. I put it in a folder named bin in my home folder.

Actually, "installation" is a bit of a misnomer. Although you can install it system-wide, it's easier to just extract and run directly. If you don't have root access then you have no choice anyay.

Create a virtualenv

This command assumes you've extracted virtualenv to a subdirectory of the bin folder in your home directory, and that you want to call this virtualenv "awesome" -- and why not?

I always put all my virtualenvs in a pyenv folder in my home directory. You may choose to put yours elsewhere -- even in your project directory. Just make sure to exclude your virtualenv from version control.

/home/yourname/bin/virtualenv/ /home/yourname/pyenv/awesome

If you have multiple versions of Python on your system, you can create a virtualenv from any of them.

For example, if your primary Python is Python 2.6, but Python 2.7 is available on your system as python2.7, create a virtualenv like this:

python2.7 /path/to/ /path/to/new/virtualenv


Once your virtualenv is installed, nothing will change on your system, because it's a sandbox. If you want to use your new private copy of Python, you'll have to "activate" it:

source /home/yourname/pyenv/awesome/bin/activate

Now when you type python or run a Python application, it will run using the Python in your virtualenv.

Note that technically you don't have to activate it -- you can call any Python script using the full path to your virtualenv python, liken this:


You could also use the full path to your virtualenv python executable in the shebang line in a Python script.

All the activate script does is set some environment variables. I like to put project-specific additions in my activate script -- mostly setting some environment variables, such as DJANGO_SETTINGS_MODULE and PYTHONPATH.


You can run deactivate (or just exit your terminal session) to go back to using your system's default Python.


Every virtualenv comes with a free installation of pip, the preferred way to install Python packages from the Python Package Index. Feel free to experiment -- virtualenvs are easy to create, and easy to recreate.

pip freeze

If your virtualenv is all set up exactly the way you like it, with all the Python modules your project needs to have "pip installed" to run, you can easily duplicate this on another machine.

First, save a list of the dependencies:

pip freeze > dependencies.txt

Then, in your new virtualenv (perhaps on your server):

pip install -r dependencies.txt

This will install not only all the same packages as your original virtualenv, but it will also ensure that they're the exact same version.

Comments !