virtualenv-sh 0.2.2

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

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

# 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.