Note: Edited comments about the --no-site-packages argument now being default, thanks to @dideler on Twitter.

Python is a very powerful scripting language. The language has lots of Python packages you can install and use in your projects. Sometimes, you may have different projects that need different versions of the same package/module. For example, let's say you're developing a web application with the latest version of Django for a customer. At the same time, you support some old projects that require Django version 1.0. In that case, you have to change the path that points to Django every time you switch the projects. It would be very handy to have some tools that allows you to switch from one environment to another without affecting each other. That tool is called virtualenv. In this article we will show you how to install Virtualenv, and get started.

Virtualenv lets you create virtual Python environments. Everything you install or remove in that environment stays there and other environments are not affected. Most importantly, you don't pollute the global package directory of your system. For example, if you want to test an unstable package, virtualenv is the best way to go. If the unstable module you're testing has some errors in the installation/uninstallation process, your system will not be affected by it. When you are ready to remove the new unstable module, what you need to do is just removing the virtualenv environment you created.

Installing Virtualenv with pip

In this article, we will be using pip as the Python Package Manager. You can also use easy_install if you like. First, let's setup up pip (You may need to become root or use sudo on a Unix machine):

[shell]
$ easy_install pip
[/shell]

The next step is to install the virtualenv package:

[shell]
$ pip install virtualenv
[/shell]

And that's it! To install virtualenv, it's very easy.

Create an Environment with virtualenv

The next step is to create the environment with virtualenv:

[shell]
virtualenv my_blog_environment
[/shell]

With the previous command, we created an isolated Python environment under the directory my_blog_environment. Note that by default in the current version of virtualenv, it uses the --no-site-packages option. This tells virtualenv to create an empty Python environment for us.

The other option would be for our virtual environment to contain all of the packages in our global Python directory (eg. C:\Python27 or /usr/lib/python2.7). If you need to do this, you can use the --use-site-package argument.

Exploring the Virtual Environment

The next step is to activate your virtual environment:

[shell]
$ cd my_blog_environment/
$ source bin/activate
[/shell]

You should now be seeing that your prompt changed a little bit (refer to the parenthesis at the beginning):

[shell]
user@hostname:~/my_blog_environment$
[/shell]

Now you're in your virtual environment. If you list the contents of the current directory (virtualenv) you will see 3 directories:

[shell]
user@hostname:~/my_blog_environment$ ls
bin  include  lib
[/shell]

The "bin" directory includes the executables for our virtualenv environment. That is the place where the Python interpreter is. Also the executables that are installed by some packages will be included in that directory. The "include" directory contains the header files of the environment. Finally, the "lib" directory includes the Python files of the installed modules of our virtualenv system.

Install Virtualenv Packages

The next step is to install some packages and use our environment. As we stated in our example let's install an old version of Django, version 1.0.

[shell]
pip install Django==1.0
[/shell]

Now, we can check if Django is installed in our virtual environment by checking in Python shell.

[python]
>>> import django
>>> print django.VERSION
(1, 0, 'final')
>>> exit()
$ deactivate
[/python]

Virtualenv Sandboxes

Another interesting feature of virtualenv is the ability to create sandboxes for different versions of Python interpreter. With the -p flag you can create environments that use different versions of the Python interpreter. Let's say for example that you want to create a project with Python's latest version 3. To be able to do that, you first need to install the version of Python you want to try on your system. After that, you need to find the path of the executable of the interpreter. You can typically find it under /usr/bin (eg. /usr/bin/python3) for Linux, and C:\ (eg. C:\Python31) for Windows.

[shell]
$ virtualenv --no-site-packages -p /usr/bin/python3 p3_test
$ cd p3_test
$ source bin/activate
$ python
Python 3.2 (r32:88445, Dec  8 2011, 15:26:51)
[GCC 4.5.2] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> print('Hello There')
Hello There
[/shell]

Now, you are ready to experiment with your new Python 3 environment.