**This page has moved to http://jonathanchu.is/posts/virtualenv-and-pip-basics/. You will be redirected there shortly.
Virtualenv and pip Basics
When doing any kind of Python development, one tool I find indispensable is virtualenv. Virtualenv, along with virtualenvwrapper and pip, make for a great way to completely isolate your development environment.
When I first started out developing Django sites, I used to use easy_install to install all packages I needed to the system-wide
site-packages directory. Even as a newbie to Django, I knew this wasn't good practice, but it ensured that commonly used libraries such as
MySQL-python was available without any extra configuration with new projects. Regardless, completely isolating your environment with virtualenv ensures that a) you don't install conflicting packages and b) any bugs introduced in your project can be traced back directly to the packages you installed. Also, a huge benefit is that it makes installing multiple versions of Python super easy without having to create any symlinks.
Getting started with Virtualenv and pip
The first thing you will need to do is install pip. If you have setuptools installed, which you most likely will with most modern platforms, you can install pip through easy_install:
Next, you'll need to install virtualenv with pip:
pip install virtualenv
Finally, I would highly recommend installing virtualenvwrapper as it makes it much easier to create and start virtual environments:
pip install virtualenvwrapper
As part of the install instructions for virtualenvwrapper, you need to add this to your .bash_profile
# virtualenv export WORKON_HOME=$HOME/.virtualenvs source /Library/Frameworks/Python.framework/Versions/2.7/bin/virtualenvwrapper.sh
*Please note that this path may differ depending on what version of Python you have. Also, I like to keep all my virtualenvs in a directory called
.virtualenvsin my home directory, but this may differ for you if you choose to keep your virtual environments in a different directory.
Make sure you source your new
...and that's it! Now you're all set to start using virtual environments!
Creating a Virtual Environment
A few handy aliases I have in my
.bash_profile are found on Doug Hellmann's blog and listed below:
# virtualenv aliases # http://blog.doughellmann.com/2010/01/virtualenvwrapper-tips-and-tricks.html alias v='workon' alias v.deactivate='deactivate' alias v.mk='mkvirtualenv --no-site-packages' alias v.mk_withsitepackages='mkvirtualenv' alias v.rm='rmvirtualenv' alias v.switch='workon' alias v.add2virtualenv='add2virtualenv' alias v.cdsitepackages='cdsitepackages' alias v.cd='cdvirtualenv' alias v.lssitepackages='lssitepackages'
This saves some keystrokes, especially since I always create new virtual environments with the
--no-site-packages switch to ensure a completely clean environment.
To create and start a new virtual environment with
$ v.mk myvirtualenv New python executable in myvirtualenv/bin/python Installing setuptools............done. (myvirtualenv) $
This creates and virtual environment and makes it active. To deactivate it, you can simply type:
(myvirtualenv) $ deactivate $
So let's go ahead and start our virtual environment once again and install some packages to it.
$ v myvirtualenv (myvirtualenv) $
We're going to install Python package
Yolk as it is a useful command line utility that lists the packages installed for the environment.
$ v myvirtualenv (myvirtualenv) $ (myvirtualenv) $ pip install yolk Downloading/unpacking yolk Downloading yolk-0.4.1.tar.gz (80Kb): 80Kb downloaded Running setup.py egg_info for package yolk Requirement already satisfied (use --upgrade to upgrade): setuptools in /Users/jonathan/.virtualenvs/myvirtualenv/lib/python2.7/site-packages/setuptools-0.6c11-py2.7.egg (from yolk) Installing collected packages: yolk Running setup.py install for yolk Installing yolk script to /Users/jonathan/.virtualenvs/myvirtualenv/bin Successfully installed yolk Cleaning up...
Now you can use
yolk -l to list the packages installed for this virtual environment:
(myvirtualenv) $ yolk -l Python - 2.7.1 - active development (/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/lib-dynload) pip - 0.8.1 - active setuptools - 0.6c11 - active wsgiref - 0.1.2 - active development (/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7) yolk - 0.4.1 - active
Here is a brief one-line example showing how to create a virtualenv and install Django, MySQL Python, South, Python Imaging Library (PIL), and ImageKit using pip:
$ v.mk newdjangoenv (newdjangoenv) $ pip install django MySQL-python south pil django-imagekit
When you have your requirements installed, it's always good to take a snapshot of the requirements and the current versions. You can do this by typing
freeze and specifying an output file:
(newdjangoenv) $ pip freeze > requirements.txt
And finally, you can use the
requirements.txt file so that your environment is completely and easily replicable:
$ pip install -r requirements.txt
And there you have it -- you can now create and test your Python applications in completely isolated environments!
For more on pip and virtualenv, check out this great post by Salty Crane which got me started on all this.