virtualenvwrapper is a set of shell functions defined in Bourne shell compatible syntax. It is tested under bash, ksh, and zsh. It may work with other shells, so if you find that it does work with a shell not listed here please let me know. If you can modify it to work with another shell, without completely rewriting it, send a pull request through the bitbucket project page. If you write a clone to work with an incompatible shell, let me know and I will link to it from this page.
virtualenvwrapper is tested under Python 2.4 - 2.7.
virtualenvwrapper should be installed into the same global site-packages area where virtualenv is installed. You may need administrative privileges to do that. The easiest way to install it is using pip:
$ pip install virtualenvwrapper
or:
$ sudo pip install virtualenvwrapper
Warning
virtualenv lets you create many different Python environments. You should only ever install virtualenv and virtualenvwrapper on your base Python installation (i.e. NOT while a virtualenv is active) so that the same release is shared by all Python environments that depend on it.
An alternative to installing it into the global site-packages is to add it to your user local directory (usually ~/.local).
$ pip install --install-option="--user" virtualenvwrapper
Add two lines to your shell startup file (.bashrc, .profile, etc.) to set the location where the virtual environments should live and the location of the script installed with this package:
export WORKON_HOME=$HOME/.virtualenvs
source /usr/local/bin/virtualenvwrapper.sh
After editing it, reload the startup file (e.g., run source ~/.bashrc).
virtualenvwrapper can be customized by changing environment variables. Set the variables in your shell startup file before loading virtualenvwrapper.sh.
The variable WORKON_HOME tells virtualenvwrapper where to place your virtual environments. The default is $HOME/.virtualenvs. If the directory does not exist when virtualenvwrapper is loaded, it will be created automatically.
The variable VIRTUALENVWRAPPER_HOOK_DIR tells virtualenvwrapper where the user-defined hooks should be placed. The default is $WORKON_HOME.
The variable VIRTUALENVWRAPPER_LOG_DIR tells virtualenvwrapper where the logs for the hook loader should be written. The default is $WORKON_HOME.
During startup, virtualenvwrapper.sh finds the first python and virtualenv programs on the $PATH and remembers them to use later. This eliminates any conflict as the $PATH changes, enabling interpreters inside virtual environments where virtualenvwrapper is not installed or where different versions of virtualenv are installed. Because of this behavior, it is important for the $PATH to be set before sourcing virtualenvwrapper.sh. For example:
export PATH=/usr/local/bin:$PATH
source /usr/local/bin/virtualenvwrapper.sh
To override the $PATH search, set the variable VIRTUALENVWRAPPER_PYTHON to the full path of the interpreter to use and VIRTUALENVWRAPPER_VIRTUALENV to the full path of the virtualenv binary to use. Both variables must be set before sourcing virtualenvwrapper.sh. For example:
export VIRTUALENVWRAPPER_PYTHON=/usr/local/bin/python
export VIRTUALENVWRAPPER_VIRTUALENV=/usr/local/bin/virtualenv
source /usr/local/bin/virtualenvwrapper.sh
If the application identified by VIRTUALENVWRAPPER_VIRTUALENV needs arguments, they can be set in VIRTUALENVWRAPPER_VIRTUALENV_ARGS. The same variable can be used to set default arguments to be passed to virtualenv. For example, set the value to --no-site-packages to ensure that all new environments are isolated from the system site-packages directory.
export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages'
virtualenvwrapper creates temporary files in $TMPDIR. If the variable is not set, it uses /tmp. To change the location of temporary files just for virtualenvwrapper, set VIRTUALENVWRAPPER_TMPDIR.
Most UNIX systems include the ability to change the configuration for all users. This typically takes one of two forms: editing the skeleton files for new accounts or editing the global startup file for a shell.
Editing the skeleton files for new accounts means that each new user will have their private startup files preconfigured to load virtualenvwrapper. They can disable it by commenting out or removing those lines. Refer to the documentation for the shell and operating system to identify the appropriate file to edit.
Modifying the global startup file for a given shell means that all users of that shell will have virtualenvwrapper enabled, and they cannot disable it. Refer to the documentation for the shell to identify the appropriate file to edit.
The shell script containing the wrapper functions has been renamed in the 2.x series to reflect the fact that shells other than bash are supported. In your startup file, change source /usr/local/bin/virtualenvwrapper_bashrc to source /usr/local/bin/virtualenvwrapper.sh.