Supported Shells

virtualenvwrapper is a set of shell functions defined in Bourneshell compatible syntax. Its automated tests run under theseshells on OS X and Linux:

  • bash
  • ksh
  • zshIt may work with other shells, so if you find that it does work with ashell not listed here please let me know. If you can modify it towork with another shell without completely rewriting it, then send a pullrequest through the bitbucket project page. If you write a clone towork with an incompatible shell, let me know and I will link to itfrom this page.

Windows Command Prompt

David Marble has ported virtualenvwrapper to Windows batch scripts,which can be run under Microsoft Windows Command Prompt. This is alsoa separately distributed re-implementation. You can downloadvirtualenvwrapper-win from PyPI.


It is possible to use virtualenv wrapper under MSYS with a native Windows Pythoninstallation. In order to make it work, you need to define an extraenvironment variable named MSYS_HOME containing the root path tothe MSYS installation.

  1. export WORKON_HOME=$HOME/.virtualenvs
  2. export MSYS_HOME=/c/msys/1.0
  3. source /usr/local/bin/


  1. export WORKON_HOME=$HOME/.virtualenvs
  2. export MSYS_HOME=C:\msys\1.0
  3. source /usr/local/bin/

Depending on your MSYS setup, you may need to install the MSYS mktempbinary in the MSYS_HOME/bin folder.


Guillermo López-Anglada has ported virtualenvwrapper to run underMicrosoft’s PowerShell. We have agreed that since it is not compatiblewith the rest of the extensions, and is largely a re-implementation(rather than an adaptation), it should be distributed separately. Youcan download virtualenvwrapper-powershell from PyPI.

Python Versions

virtualenvwrapper is tested under Python 2.7-3.6.

Basic Installation

virtualenvwrapper should be installed into the same globalsite-packages area where virtualenv is installed. You may needadministrative privileges to do that. The easiest way to install itis using pip:

  1. $ pip install virtualenvwrapper


  1. $ sudo pip install virtualenvwrapper


virtualenv lets you create many different Python environments. Youshould only ever install virtualenv and virtualenvwrapper on yourbase Python installation (i.e. NOT while a virtualenv is active)so that the same release is shared by all Python environments thatdepend on it.

An alternative to installing it into the global site-packages is toadd it to your user local directory(usually ~/.local).

  1. $ pip install --user virtualenvwrapper

Shell Startup File

Add three lines to your shell startup file (.bashrc, .profile,etc.) to set the location where the virtual environments should live,the location of your development project directories, and the locationof the script installed with this package:

  1. export WORKON_HOME=$HOME/.virtualenvs
  2. export PROJECT_HOME=$HOME/Devel
  3. source /usr/local/bin/

After editing it, reload the startup file (e.g., run source~/.bashrc).

Lazy Loading

An alternative initialization script is provided for loadingvirtualenvwrapper lazily. Instead of sourcing virtualenvwrapper.shdirectly, use is not on your $PATH, setVIRTUALENVWRAPPER_SCRIPT to point to it.

  1. export WORKON_HOME=$HOME/.virtualenvs
  2. export PROJECT_HOME=$HOME/Devel
  3. export VIRTUALENVWRAPPER_SCRIPT=/usr/local/bin/
  4. source /usr/local/bin/


When the lazy-loading version of the startup script is used,tab-completion of arguments to virtualenvwrapper commands (such asenvironment names) is not enabled until after the first command hasbeen run. For example, tab completion of environments does not workfor the first instance of workon.


  • Run: workon
  • A list of environments, empty, is printed.
  • Run: mkvirtualenv temp
  • A new environment, temp is created and activated.
  • Run: workon
  • This time, the temp environment is included.


virtualenvwrapper can be customized by changing environmentvariables. Set the variables in your shell startup file _before_loading

Location of Environments

The variable WORKON_HOME tells virtualenvwrapper where to placeyour virtual environments. The default is $HOME/.virtualenvs. Ifthe directory does not exist when virtualenvwrapper is loaded, it willbe created automatically.

Location of Project Directories

The variable PROJECT_HOME tells virtualenvwrapper where to placeyour project working directories. The variable must be set and thedirectory created before mkproject is used.

See also

Project Linkage Filename

The variable VIRTUALENVWRAPPER_PROJECT_FILENAME tellsvirtualenvwrapper how to name the file linking a virtualenv to aproject working directory. The default is .project.

See also

Enable Project Directory Switching

The variable VIRTUALENVWRAPPER_WORKON_CD controls whether theworking directory is changed during the post activate phase. Thedefault is 1, to enable changing directories. Set the value to0 to disable this behavior for all invocations of workon.

See also

Location of Hook Scripts

The variable VIRTUALENVWRAPPER_HOOK_DIR tells virtualenvwrapperwhere the user-defined hooks should be placed. Thedefault is $WORKON_HOME.

See also

Location of Hook Logs

The variable VIRTUALENVWRAPPER_LOG_FILE tells virtualenvwrapperwhere the logs for the hook loader should be written. The default isto not log from the hooks.

Python Interpreter, virtualenv, and $PATH

During startup, finds the first pythonand virtualenv programs on the $PATH and remembers them to uselater. This eliminates any conflict as the $PATH changes,enabling interpreters inside virtual environments wherevirtualenvwrapper is not installed or where different versions ofvirtualenv are installed. Because of this behavior, it is importantfor the $PATH to be set before For example:

  1. export PATH=/usr/local/bin:$PATH
  2. source /usr/local/bin/

To override the $PATH search, set the variableVIRTUALENVWRAPPERPYTHON to the full path of the interpreter touse and VIRTUALENVWRAPPER_VIRTUALENV to the full path of thevirtualenv binary to use. Both variables _must be set beforesourcing For example:

  1. export VIRTUALENVWRAPPER_PYTHON=/usr/local/bin/python
  2. export VIRTUALENVWRAPPER_VIRTUALENV=/usr/local/bin/virtualenv
  3. source /usr/local/bin/

Default Arguments for virtualenv

If the application identified by VIRTUALENVWRAPPER_VIRTUALENVneeds arguments, they can be set inVIRTUALENVWRAPPER_VIRTUALENV_ARGS. The same variable can be usedto set default arguments to be passed to virtualenv. For example,set the value to —no-site-packages to ensure that all newenvironments are isolated from the system site-packages directory.

  1. export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages'

Temporary Files

virtualenvwrapper creates temporary files in $TMPDIR. If thevariable is not set, it uses /tmp. To change the location oftemporary files just for virtualenvwrapper, setVIRTUALENVWRAPPER_TMPDIR.

Site-wide Configuration

Most UNIX systems include the ability to change the configuration forall users. This typically takes one of two forms: editing theskeleton files for new accounts or editing the global startup filefor a shell.

Editing the skeleton files for new accounts means that each new userwill have their private startup files preconfigured to loadvirtualenvwrapper. They can disable it by commenting out or removingthose lines. Refer to the documentation for the shell and operatingsystem to identify the appropriate file to edit.

Modifying the global startup file for a given shell means that allusers of that shell will have virtualenvwrapper enabled, and theycannot disable it. Refer to the documentation for the shell toidentify the appropriate file to edit.

Upgrading to 2.9

Version 2.9 includes the features previously delivered separately byvirtualenvwrapper.project. If you have an older verison of theproject extensions installed, remove them before upgrading.

Upgrading from 1.x

The shell script containing the wrapper functions has been renamed inthe 2.x series to reflect the fact that shells other than bash aresupported. In your startup file, change source/usr/local/bin/virtualenvwrapper_bashrc to source/usr/local/bin/