Tips for using Pip + Virtualenv + Virtualenvwrapper

UPDATE 2018-07-09: the standards for Python environments have changed a bit since this post was written, consider using the built-in venv feature within Python. I often setup stuff locally now with something like following:

python3 -m venv .venv # requires Python >= 3.6
. .venv/bin/activate.sh # or .fish or whatever your shell is
pip3 install -r requirements.txt
# also add .venv to your .gitignore

I love using pip + virtualenv + virtualenvwrapper for my python projects! I first started using it so I could work on two projects that were using different versions of django on the same laptop and easily switch between the different dependencies. If you work on a lot of different python projects and don’t have it setup yet, here’s some info on getting it setup on a Mac*. This is what each one does:

• pip - makes installing and uninstalling python packages easier than easy_install
• virtualenv - let's you keep python dependencies in an isolated environment
• virtualenvwrapper - makes virtualenv usable, by managing where dependencies are stored and including a bunch of convenient scripts

*The one change I’d make to that tutorial is to change vi .bash_login to emacs ~/.profile ;?j

Custom aliases

For customization, I like adding these aliases, which naming-wise I find way easier to remember:

alias v='workon'
alias v.deactivate='deactivate'
alias v.mk='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'

Doug Hellmann linked to them on this post of tips and tricks, but the page he was linking to doesn’t exist anymore. If you’re not into setting up aliases, don’t forget that the regular function names are meant to be tab-completed instead of being fully typed out.

Hot tips

Basic use

# see available virtualenvs
workon

# use a specific virtualenv (called "mrcoles")
workon mrcoles

# create a new virtualenv (called "mrcoles" that will reside 
# in ~/.virtualenvs/mrcoles)
# optional: the -a `pwd` makes it always cd into your current dir
# optional: the -r requirements.txt will pip install requirements
mkvirtualenv mrcoles -a `pwd` -r requirements.txt

# disable your current virtualenv
deactivate

Create a .project file

If you didn’t use the -a command when making your environment, then add a file called .project into your virtualenv folder with the path to your environment and whenever you activate that environment, it’ll automatically cd you into that directory. If your virtualenv were called "mrcoles", then you could quickly do this from your project’s root directory as so:

# an example of setting the project path in your virtualenv
pwd > ~/.virtualenvs/mrcoles/.project

Add custom environment variables to your postactivate script

If you’re working on a django project, then you should team up your virtualenv with your PYTHONPATH and DJANGO_SETTINGS_MODULE environment variables. Here’s an example of how I set it up for my site:

# an example of setting environment variables for a django project to your virtual env
cat >> ~/.virtualenvs/mrcoles/bin/postactivate

export PYTHONPATH=~/projects/mrcoles/
export DJANGO_SETTINGS_MODULE="project.settings"

*remember to deactivate and reactivate your virtualenv to get the benefits of this script the first time you create it (or just source it)

How to record and install dependencies

Once it’s up and running you can easily manage your environments and use pip to record and install dependencies:

# create a requirements file
pip freeze > requirements.txt

# install requirements
pip install -r requirements.txt

You can also run pip freeze to just list off which dependencies are installed in your environment.

Related Posts:
A menu shortcut for activating virtualenvs
mkdjangovirtualenv: an easier way to setup a virtualenv for django projects