virtualenvwrapper is a set of shell functions defined in Bourne shell compatible syntax. Its automated tests run under these shells on OS X and Linux:
It may work with other shells, so if you find that it does work with a shell not listed here please let us know. If you can modify it to work with another shell without completely rewriting it, then send a pull request through the GitHub project page. If you write a clone to work with an incompatible shell, let us know and we will link to it from 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 also a separately distributed re-implementation. You can download virtualenvwrapper-win from PyPI.
It is possible to use virtualenv wrapper under MSYS with a native Windows Python
installation. In order to make it work, you need to define an extra
environment variable named
MSYS_HOME containing the root path to
the MSYS installation.
export WORKON_HOME=$HOME/.virtualenvs export MSYS_HOME=/c/msys/1.0 source /usr/local/bin/virtualenvwrapper.sh
export WORKON_HOME=$HOME/.virtualenvs export MSYS_HOME=C:\msys\1.0 source /usr/local/bin/virtualenvwrapper.sh
Depending on your MSYS setup, you may need to install the MSYS mktemp
binary in the
Guillermo López-Anglada has ported virtualenvwrapper to run under Microsoft’s PowerShell. We have agreed that since it is not compatible with the rest of the extensions, and is largely a re-implementation (rather than an adaptation), it should be distributed separately. You can download virtualenvwrapper-powershell from PyPI.
virtualenvwrapper is tested under Python 2.7-3.6.
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
$ sudo pip install virtualenvwrapper
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 --user virtualenvwrapper
Shell Startup File¶
Add three lines to your shell startup file (
etc.) to set the location where the virtual environments should live,
the location of your development project directories, and the location
of the script installed with this package:
export WORKON_HOME=$HOME/.virtualenvs export PROJECT_HOME=$HOME/Devel source /usr/local/bin/virtualenvwrapper.sh
After editing it, reload the startup file (e.g., run
An alternative initialization script is provided for loading
virtualenvwrapper lazily. Instead of sourcing
virtualenvwrapper.sh is not on your
VIRTUALENVWRAPPER_SCRIPT to point to it.
export WORKON_HOME=$HOME/.virtualenvs export PROJECT_HOME=$HOME/Devel export VIRTUALENVWRAPPER_SCRIPT=/usr/local/bin/virtualenvwrapper.sh source /usr/local/bin/virtualenvwrapper_lazy.sh
When the lazy-loading version of the startup script is used, tab-completion of arguments to virtualenvwrapper commands (such as environment names) is not enabled until after the first command has been run. For example, tab completion of environments does not work for the first instance of workon.
- A list of environments, empty, is printed.
- A new environment,
tempis created and activated.
- This time, the
tempenvironment is included.
virtualenvwrapper can be customized by changing environment
variables. Set the variables in your shell startup file before
Location of Environments¶
WORKON_HOME tells virtualenvwrapper where to place
your virtual environments. The default is
the directory does not exist when virtualenvwrapper is loaded, it will
be created automatically.
Location of Project Directories¶
PROJECT_HOME tells virtualenvwrapper where to place
your project working directories. The variable must be set and the
directory created before mkproject is used.
Project Linkage Filename¶
virtualenvwrapper how to name the file linking a virtualenv to a
project working directory. The default is
Enable Project Directory Switching¶
VIRTUALENVWRAPPER_WORKON_CD controls whether the
working directory is changed during the post activate phase. The
1, to enable changing directories. Set the value to
0 to disable this behavior for all invocations of
Location of Hook Scripts¶
VIRTUALENVWRAPPER_HOOK_DIR tells virtualenvwrapper
where the user-defined hooks should be placed. The
Location of Hook Logs¶
VIRTUALENVWRAPPER_LOG_FILE tells virtualenvwrapper
where the logs for the hook loader should be written. The default is
to not log from the hooks.
Python Interpreter, virtualenv, and $PATH¶
virtualenvwrapper.sh finds the first
virtualenv programs on the
$PATH and remembers them to use
later. This eliminates any conflict as the
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
$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
VIRTUALENVWRAPPER_VIRTUALENV to the full path of the
virtualenv binary to use. Both variables must be set before
virtualenvwrapper.sh. For example:
export VIRTUALENVWRAPPER_PYTHON=/usr/local/bin/python export VIRTUALENVWRAPPER_VIRTUALENV=/usr/local/bin/virtualenv source /usr/local/bin/virtualenvwrapper.sh
Default Arguments for virtualenv¶
If the application identified by
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
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
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.
Upgrading to 2.9¶
Version 2.9 includes the features previously delivered separately by
virtualenvwrapper.project. If you have an older verison of the
project extensions installed, remove them before upgrading.
Upgrading from 1.x¶
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