Virtualenv Quickstart Guide

Why use virtualenv?

Virtualenv (http://www.virtualenv.org/) basically provides you with a full Python environment (and/or versions) inside a single folder. This way, you can have multiple Python environments next to each other (usually one per project), each with its own binaries and packages.

I really recommend using virtualenv for all Python projects. Tools like virtualenvwrapper and requirements files make setting up a new virtual environment a breeze.

Setup

In case you're still using easy_install to install Python packages, you should switch to pip immediately:

$ sudo easy_install pip

Then install virtualenv itself:

$ sudo pip install virtualenv

Those are usually the only two Python packages that you should install to your systemwide PYTHONPATH.

Creating a virtualenv

Now you need to initialize your virtual environment. This can be located anywhere. I'd recommend either creating it into a folder called VIRTUAL inside your project directory, or creating a folder called .virtualenv in your home directory and placing it in there, named like your project.

$ virtualenv --no-site-packages VIRTUAL
New python executable in VIRTUAL/bin/python
Installing setuptools............done.
Installing pip...............done.

Enabling a virtualenv

To actually work inside a virtualenv, you need to enable it first. This is done by sourcing bin/activate inside your virtualenv folder.

$ source VIRTUAL/bin/activate

This step needs to be done each time you start a new bash prompt. Now every time you call a Python-related binary (e.g. python or pip), the version from your virtualenv instead of the system version will be used.

You can also use your virtual python without sourcing the mentioned file first, but then you need to specify the full path to the desired binary (e.g. VIRTUAL/bin/python manage.py runserver). This can be useful for bash scripts.

Installing packages, tracking requirements

Installing Python packages is as simple as pip install <packagename> after enabling your virtualenv. When having worked inside a virtualenv for a while, you've probably installed a few packages and want to document those dependencies somehow. This is where the pip freeze command and requirements.txt files can and should be used.

$ pip install Django
...
$ pip freeze > requirements.txt
$ cat requirements.txt
Django==1.4.1
wsgiref==0.1.2

(Note: The wsgiref package is a part of the Python standard library. Currently it is the only standard library package that includes package metadata, so it is the only standard library package whose presence pip reports.)

The requirements.txt file is a very good convention, as it allows you or another developer to quickly replicate the environment you're currently working in. After creating an empty virtualenv, you can simply install all necessary packages with:

$ pip install -r requirements.txt

For more information, please refer to the pip docs.

Next steps

To simplify your life with virtualenv, you should start using virtualenvwrapper, which gives you nice shortcut functions like mkvirtualenv to create a new environment, workon to enable a specific virtual environment, rmvirtualenv to remove an environment and more.

This should be enough to get you started. In case some parts of this quickstart guide are difficult to understand or if you have any questions, please leave a comment below.