Provided by: virtualenvwrapper_4.8.4-4ubuntu1_all 
NAME
virtualenvwrapper - a set of wrappers to assist with manage your python virtualenvs
All of the commands below are to be used on the Terminal command line.
MANAGING ENVIRONMENTS
mkvirtualenv
Create a new environment, in the WORKON_HOME.
Syntax:
mkvirtualenv [-a project_path] [-i package] [-r requirements_file] [virtualenv options] ENVNAME
All command line options except -a, -i, -r, and -h are passed directly to virtualenv. The new
environment is automatically activated after being initialized.
$ workon
$ mkvirtualenv mynewenv
New python executable in mynewenv/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(mynewenv)$ workon
mynewenv
(mynewenv)$
The -a option can be used to associate an existing project directory with the new environment.
The -i option can be used to install one or more packages (by repeating the option) after the environment
is created.
The -r option can be used to specify a text file listing packages to be installed. The argument value is
passed to pip -r to be installed.
SEE ALSO:
• premkvirtualenv
• postmkvirtualenv
• requirements file format
mktmpenv
Create a new virtualenv in the WORKON_HOME directory.
Syntax:
mktmpenv [(-c|--cd)|(-n|--no-cd)] [VIRTUALENV_OPTIONS]
A unique virtualenv name is generated.
If -c or --cd is specified the working directory is changed to the virtualenv directory during the
post-activate phase, regardless of the value of VIRTUALENVWRAPPER_WORKON_CD.
If -n or --no-cd is specified the working directory is not changed to the virtualenv directory during the
post-activate phase, regardless of the value of VIRTUALENVWRAPPER_WORKON_CD.
$ mktmpenv
Using real prefix '/Library/Frameworks/Python.framework/Versions/2.7'
New python executable in 1e513ac6-616e-4d56-9aa5-9d0a3b305e20/bin/python
Overwriting 1e513ac6-616e-4d56-9aa5-9d0a3b305e20/lib/python2.7/distutils/__init__.py
with new content
Installing setuptools...............................................
....................................................................
.................................................................done.
This is a temporary environment. It will be deleted when deactivated.
(1e513ac6-616e-4d56-9aa5-9d0a3b305e20) $
lsvirtualenv
List all of the environments.
Syntax:
lsvirtualenv [-b] [-l] [-h]
-b Brief mode, disables verbose output.
-l Long mode, enables verbose output. Default.
-h Print the help for lsvirtualenv.
SEE ALSO:
• get_env_details
showvirtualenv
Show the details for a single virtualenv.
Syntax:
showvirtualenv [env]
SEE ALSO:
• get_env_details
rmvirtualenv
Remove an environment, in the WORKON_HOME.
Syntax:
rmvirtualenv ENVNAME
You must use deactivate before removing the current environment.
(mynewenv)$ deactivate
$ rmvirtualenv mynewenv
$ workon
$
SEE ALSO:
• prermvirtualenv
• postrmvirtualenv
cpvirtualenv
Duplicate an existing virtualenv environment. The source can be an environment managed by
virtualenvwrapper or an external environment created elsewhere.
WARNING:
Copying virtual environments is not well supported. Each virtualenv has path information hard-coded
into it, and there may be cases where the copy code does not know it needs to update a particular
file. Use with caution.
Syntax:
cpvirtualenv ENVNAME [TARGETENVNAME]
NOTE:
Target environment name is required for WORKON_HOME duplications. However, target environment name can
be ommited for importing external environments. If omitted, the new environment is given the same name
as the original.
$ workon
$ mkvirtualenv source
New python executable in source/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(source)$ cpvirtualenv source dest
Making script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/easy_install relative
Making script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/easy_install-2.6 relative
Making script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/pip relative
Script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/postactivate cannot be made relative (it's not a normal script that starts with #!/Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/python)
Script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/postdeactivate cannot be made relative (it's not a normal script that starts with #!/Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/python)
Script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/preactivate cannot be made relative (it's not a normal script that starts with #!/Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/python)
Script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/predeactivate cannot be made relative (it's not a normal script that starts with #!/Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/python)
(dest)$ workon
dest
source
(dest)$
SEE ALSO:
• precpvirtualenv
• postcpvirtualenv
• premkvirtualenv
• postmkvirtualenv
allvirtualenv
Run a command in all virtualenvs under WORKON_HOME.
Syntax:
allvirtualenv command with arguments
Each virtualenv is activated, bypassing activation hooks, the current working directory is changed to the
current virtualenv, and then the command is run. Commands cannot modify the current shell state, but can
modify the virtualenv.
$ allvirtualenv pip install -U pip
CONTROLLING THE ACTIVE ENVIRONMENT
workon
List or change working virtual environments
Syntax:
workon [(-c|--cd)|(-n|--no-cd)] [environment_name|"."]
If no environment_name is given the list of available environments is printed to stdout.
If -c or --cd is specified the working directory is changed to the project directory during the
post-activate phase, regardless of the value of VIRTUALENVWRAPPER_WORKON_CD.
If -n or --no-cd is specified the working directory is not changed to the project directory during the
post-activate phase, regardless of the value of VIRTUALENVWRAPPER_WORKON_CD.
If "." is passed as the environment name, the name is derived from the base name of the current working
directory (contributed by Matias Saguir).
$ workon
$ mkvirtualenv env1
New python executable in env1/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(env1)$ mkvirtualenv env2
New python executable in env2/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(env2)$ workon
env1
env2
(env2)$ workon env1
(env1)$ echo $VIRTUAL_ENV
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env1
(env1)$ workon env2
(env2)$ echo $VIRTUAL_ENV
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env2
(env2)$
SEE ALSO:
• predeactivate
• postdeactivate
• preactivate
• postactivate
• Enable Project Directory Switching
deactivate
Switch from a virtual environment to the system-installed version of Python.
Syntax:
deactivate
NOTE:
This command is actually part of virtualenv, but is wrapped to provide before and after hooks, just as
workon does for activate.
$ workon
$ echo $VIRTUAL_ENV
$ mkvirtualenv env1
New python executable in env1/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(env1)$ echo $VIRTUAL_ENV
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env1
(env1)$ deactivate
$ echo $VIRTUAL_ENV
$
SEE ALSO:
• predeactivate
• postdeactivate
QUICKLY NAVIGATING TO A VIRTUALENV
There are two functions to provide shortcuts to navigate into the currently-active virtualenv.
cdvirtualenv
Change the current working directory to $VIRTUAL_ENV.
Syntax:
cdvirtualenv [subdir]
Calling cdvirtualenv changes the current working directory to the top of the virtualenv ($VIRTUAL_ENV).
An optional argument is appended to the path, allowing navigation directly into a subdirectory.
$ mkvirtualenv env1
New python executable in env1/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(env1)$ echo $VIRTUAL_ENV
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env1
(env1)$ cdvirtualenv
(env1)$ pwd
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env1
(env1)$ cdvirtualenv bin
(env1)$ pwd
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env1/bin
cdsitepackages
Change the current working directory to the site-packages for $VIRTUAL_ENV.
Syntax:
cdsitepackages [subdir]
Because the exact path to the site-packages directory in the virtualenv depends on the version of Python,
cdsitepackages is provided as a shortcut for cdvirtualenv lib/python${pyvers}/site-packages. An optional
argument is also allowed, to specify a directory hierarchy within the site-packages directory to change
into.
$ mkvirtualenv env1
New python executable in env1/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(env1)$ echo $VIRTUAL_ENV
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env1
(env1)$ cdsitepackages PyMOTW/bisect/
(env1)$ pwd
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env1/lib/python2.6/site-packages/PyMOTW/bisect
lssitepackages
Calling lssitepackages shows the content of the site-packages directory of the currently-active
virtualenv.
Syntax:
lssitepackages
$ mkvirtualenv env1
New python executable in env1/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(env1)$ $ workon env1
(env1)$ lssitepackages
setuptools-0.6.10-py2.6.egg pip-0.6.3-py2.6.egg
easy-install.pth setuptools.pth
PATH MANAGEMENT
add2virtualenv
Adds the specified directories to the Python path for the currently-active virtualenv.
Syntax:
add2virtualenv directory1 directory2 ...
Sometimes it is desirable to share installed packages that are not in the system site-packages directory
and which should not be installed in each virtualenv. One possible solution is to symlink the source
into the environment site-packages directory, but it is also easy to add extra directories to the
PYTHONPATH by including them in a .pth file inside site-packages using add2virtualenv.
1. Check out the source for a big project, such as Django.
2. Run: add2virtualenv path_to_source.
3. Run: add2virtualenv.
4. A usage message and list of current "extra" paths is printed.
5. Use option -d to remove the added path.
The directory names are added to a path file named _virtualenv_path_extensions.pth inside the
site-packages directory for the environment.
Based on a contribution from James Bennett and Jannis Leidel.
toggleglobalsitepackages
Controls whether the active virtualenv will access the packages in the global Python site-packages
directory.
Syntax:
toggleglobalsitepackages [-q]
Outputs the new state of the virtualenv. Use the -q switch to turn off all output.
$ mkvirtualenv env1
New python executable in env1/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(env1)$ toggleglobalsitepackages
Disabled global site-packages
(env1)$ toggleglobalsitepackages
Enabled global site-packages
(env1)$ toggleglobalsitepackages -q
(env1)$
PROJECT DIRECTORY MANAGEMENT
SEE ALSO:
Project Management
mkproject
Create a new virtualenv in the WORKON_HOME and project directory in PROJECT_HOME.
Syntax:
mkproject [-f|--force] [-t template] [virtualenv_options] ENVNAME
-f, --force
Create the virtualenv even if the project directory already exists
The template option may be repeated to have several templates used to create a new project. The
templates are applied in the order named on the command line. All other options are passed to
mkvirtualenv to create a virtual environment with the same name as the project.
$ mkproject myproj
New python executable in myproj/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
Creating /Users/dhellmann/Devel/myproj
(myproj)$ pwd
/Users/dhellmann/Devel/myproj
(myproj)$ echo $VIRTUAL_ENV
/Users/dhellmann/Envs/myproj
(myproj)$
SEE ALSO:
• premkproject
• postmkproject
setvirtualenvproject
Bind an existing virtualenv to an existing project.
Syntax:
setvirtualenvproject [virtualenv_path project_path]
The arguments to setvirtualenvproject are the full paths to the virtualenv and project directory. An
association is made so that when workon activates the virtualenv the project is also activated.
$ mkproject myproj
New python executable in myproj/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
Creating /Users/dhellmann/Devel/myproj
(myproj)$ mkvirtualenv myproj_new_libs
New python executable in myproj/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
Creating /Users/dhellmann/Devel/myproj
(myproj_new_libs)$ setvirtualenvproject $VIRTUAL_ENV $(pwd)
When no arguments are given, the current virtualenv and current directory are assumed.
Any number of virtualenvs can refer to the same project directory, making it easy to switch between
versions of Python or other dependencies for testing.
cdproject
Change the current working directory to the one specified as the project directory for the active
virtualenv.
Syntax:
cdproject
MANAGING INSTALLED PACKAGES
wipeenv
Remove all of the installed third-party packages in the current virtualenv.
Syntax:
wipeenv
OTHER COMMANDS
virtualenvwrapper
Print a list of commands and their descriptions as basic help output.
Syntax:
virtualenvwrapper
COPYRIGHT
2009-2024, Doug Hellmann
4.8.4 Feb 14, 2024 VIRTUALENVWRAPPER(1)