Python virtualenv for development and deployment

Introduction

This how-to is provided because I've spent several hours in order to accomplish a simple recommendation in the Django documentation to use virtual environments for developing. I wasn't able to find a concise and simple way to do this and had to take a dive in several pieces of general Python tools: pip, virtualenv and virtualenvwrapper.

Setting up the environment

I'm running Ubuntu 12.04 and the Python 2.7.3 default interpreter. This is supposed to work on Debian Wheezy (7.0) too.

Install pip

In order to be able to install PyPi packages, we need to use the pip installer.

Install it:

sudo apt-get install python-pip

Initialize a virtualenv

Using a virtualenv in Python to develop and run your application in is highly recommended in order to be able to satisfy the latest dependencies on the usually 'older' Ubuntu system.

I really like to use virtualenvwrapper for this task.

Let's install it:

sudo pip install virtualenvwrapper

Above is the last global pip command we've used and the last requiring root privileges - everything from here on will be inside a virtual environment within your home directory!

Heads up!

Avoid the use of pip for installing Python packages system-wide. I'm encouraging the use of pip, but only inside a virtualenv. We need to install virtualenv and virtualenvwrapper, so those are the only ones we're installing system-wide.

The actual environments are to be located in a directory of your choice. I like to use the suggested default ~/Envs. Execute these commands (customize the directory if you like):

export WORKON_HOME=~/Envs
mkdir -p $WORKON_HOME
source /usr/local/bin/virtualenvwrapper.sh

Install the last line in your shell startup file as well, unless you want to type it in every newly opened shell:

echo "source /usr/local/bin/virtualenvwrapper.sh" >> ~/.profile

Using virtualenvs with virtualenvwrapper

Creating a new environment

To create a new environment with the name env1, do:

mkvirtualenv env1

Create as many as you like.

Managing environments

The /usr/local/bin/virtualenvwrapper.sh script added to your shell startup provided a prompt prefix to list which environment you're currently in. E.g.:

(env2) gert@gert-laptop:~ $

It also provides a whole set of commands to manage them:

List environments: lsvirtualenv or workon (without arguments)
Copy: cpvirtualenv env1 env2 (you'll now be on ''env2'')
Remove: rmvirtualenv

Entering/Leaving environments

To enter another environment:

workon env2

to move to ''env2''.

To leave any environment and go back to the general system environment (this was hard to find - undocumented!):

deactivate

Environments vs Projects

From the Virtualenvwrapper documentation on Project management you'll notice it has a feature to use in your projects. What's this about? Well, it's very simple—suppose you have a Python code project and you want to bind it one-to-one to a specific environment, then this is what projects are for.

Binding a virtualenv to a project directory will result in nothing more than changing to the project directory whenever you use the workon command.

Setting/changing a project directory to the environment is just this (run being inside the project dir):

setvirtualenvproject

Package management

Using pip

The version of pip we installed on the system is different from the one installed in the environments. Please check this to have at least version 1.3 in your environments:

gert@gert-laptop:~ $ pip --version
pip 1.0 from /usr/lib/python2.7/dist-packages (python 2.7)
gert@gert-laptop:~ $ workon env2
(env2) gert@gert-laptop:~ $ pip --version
pip 1.3.1 from /home/gert/Envs/env1/lib/python2.7/site-packages/pip-1.3.1-py2.7.egg (python 2.7)

Within a virtual environment...

Install: pip install packagename
Install specific version (e.g. Django 1.5): pip install Django==1.5
List all available packages in the environment: pip list
List packages only installed locally: pip list --local
List in the special Requirements format (see below): pip freeze
Uninstall: pip uninstall packagename

Requirements file

Just like you installed the package using pip, you can create a specification for all the packages your project requires. For each package put it on a new line. Example:

Django==1.5
ipython

Or list those using

pip freeze

This file is usually called requirements.txt for a Python project. Users are then able to satisfy these easily by issuing:

pip install -r requirements.txt