virtualenv-sh 0.2.2

Convenient shell interface to virtualenv

This project is my personal substitute for the venerable virtualenvwrapper (a set of shell functions to facilitate the use of virtualenv). Like many, I’ve used virtualenvwrapper for years, but it’s gotten a bit heavy over time. I eventually found myself waiting too long for new shells to start up, even though I tended to use only the basic features.

This project is an attempt to solve that problem. I borrowed the clever bits of virtualenvwrapper, discarded everything I considered expensive or just not interesting, and added a feature or two of my own. The number one priority of this project is speed. The code is almost pure shell script, although there may be one or two invocations of standard tools like grep or sed.

Be warned that this implementation may not be for you. I may have gotten rid of a feature that you liked, either because it was expensive or because I just didn’t care about it. I may have accidentally discarded a fix or workaround for some environment that I haven’t encountered. I may have just introduced new bugs (shell is an easy language to get wrong in subtle ways). Proceed at your own risk.

Installing

virtualenv-sh can be installed with pip or easy_install. To use it, you need to source a single shell script in your shell environment. By default, pip or easy_install should install it to /usr/local/bin. If you’re using bash or zsh, you should import the shell-specific script; otherwise, you can try the generic one. Add one of the following to your shell’s init script (.bashrc, .zshrc, etc.):

. /usr/local/bin/virtualenv-sh.bash

. /usr/local/bin/virtualenv-sh.zsh

. /usr/local/bin/virtualenv-sh.sh

Nothing else is required. There’s only one environment variable that you can use for configuration, which is WORKON_HOME. This is a path to your collection of virutalenvs; you can leave it blank to accept the default of ${HOME}/.virtualenvs. It is assumed that virtualenv itself is in your path.

WORKON_HOME=${HOME}/.virtualenvs

zsh

If you’re using zsh, you can instead use the precompiled function archive for optimal performance, although this needs to be compiled from source on your machine. You can download the source directly or try:

> pip install --upgrade --no-install virtualenv-sh
> cd build/virtualenv-sh
> sudo make install

This will find zsh in your path, use it to compile virtualenv-sh.zwc, and install it to /usr/local/bin. You can now autoload these functions and initialize virtualenv-sh. You may want to refer to the section on function autoloading in the zsh manual if you’re not familiar with this process:

# Configure all virtualenv-sh functions for autoloading
fpath=(/usr/local/bin/virtualenv-sh $fpath)
autoload -w /usr/local/bin/virtualenv-sh

# Call the main initialization function
virtualenv_sh_init

Using

The basic commands of virtualenv-sh are essentially the same as virtualenvwrapper. Here’s a brief recap:

mkvirtualenv <env_name>

Creates a new virtual_env in $WORKON_HOME. All arguments are passed directly to virtualenv. The new virtual_env will become active. Unlike virtualenvwrapper, this takes no additional arguments.

rmvirtualenv <env_name>

Deletes an existing virtual_env. If this virtual_env is currently active, it is deactivated first as a courtesy.

workon [<env_name>]

Activates the named virtual_env. If another virtual_env is currently active, it will be deactivated first. Without arguments, it will list the available virtual_envs. In compatible shells, you can choose a virtual_env from a menu.

autoworkon

Automatically sets the virtual_env based on special files. See below.

deactivate

Deactivates the current virtual_env (as when using virtualenv directly).

lsvirtualenvs

Prints a list of the virtual_envs you’ve created.

cdvirtualenv [subdir]

Changes the current directory to the root of the active virtual_env, or a subdirectory thereof.

lssitepackages

Lists the contents of the active virtual_env’s site-packages directory.

cdsitepackages [subdir]

Changes the currect directory to the site-packages directory of the active virtual_env, or a subdirectory thereof.

Hooks

virtualenv-sh supports the same global and local (per-env) hooks as virtualenvwrapper. Global hooks are files in $WORKON_HOME; local hooks are files in $WORKON_HOME/{virtual_env}/bin. Hooks are executed by sourcing them in the current shell context.

initialize (global)

Called at the end of virtualenv_sh_init.

premkvirtualenv, postmkvirtualv, prermvirtualenv, postmkvirtualenv (global)

Called at the beginning and end of mkvirtualenv and rmvirtualenv.

preactivate, postactivate (global, local); predeactivate, postdeactivate (local, global)

Called in the order indicated around activation and deactivation of a virtual_env.

In addition, virtualenv-sh allows you to dynamically register functions to be called when executing hooks:

virtualenv_sh_add_hook <hook_name> <function_name>
virtualenv_sh_remove_hook <hook_name> <function_name>

e.g.:

my_virtualenv_cleanup()
{
    # Do some stuff here
}

virtualenv_sh_add_hook postdeactivate my_virtualenv_cleanup

Registered hook functions are always executed after all global and local hook scripts.

autoworkon

autoworkon is a new command that is designed to automatically update your virtual_env based on your current directory. Note that there is no standard shell mechanism for running a function when the current directory changes–and many shells don’t have such a mechanism–so installing this is up to you. If you’re using zsh, you would use:

autoload -U add-zsh-hook
add-zsh-hook chpwd autoworkon

The autoworkon function will walk up the filesystem from the current directory until it either reaches the root or finds an item named “.workon”. If this is a readable file, it will treat the first line as the name of a virtual_env and activate it. There are a few special rules to keep in mind:

• autoworkon always stops at the first .workon it finds. It’s perfectly reasonable to have .workon files at multiple points in a directory tree to use different virtual_envs at different levels.

• An empty or unreadable .workon file is interpreted as “no virtual_env”. This is useful if you want to deactivate the automatic virtual_env in a particular subtree.

• If you activate a virtual_env manually, autoworkon will never override it. autoworkon will only change your active virtual_env if it is unset or was previously set by autoworkon.