Table Of Contents

Previous topic

Installation

Next topic

Customizing Virtualenvwrapper

This Page

Command Reference

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 [options] ENVNAME

All command line options 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 distribute.............................................
..................................................................
..................................................................
done.
(mynewenv)$ workon
mynewenv
(mynewenv)$

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

showvirtualenv

Show the details for a single virtualenv.

Syntax:

showvirtualenv [env]

See also

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
$

cpvirtualenv

Duplicate an environment, in the WORKON_HOME.

Syntax:

cpvirtualenv ENVNAME TARGETENVNAME

Note

The environment created by the copy operation is made relocatable.

$ workon
$ mkvirtualenv source
New python executable in source/bin/python
Installing distribute.............................................
..................................................................
..................................................................
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)$

Controlling the Active Environment

workon

List or change working virtual environments

Syntax:

workon [environment_name]

If no environment_name is given the list of available environments is printed to stdout.

$ workon
$ mkvirtualenv env1
  New python executable in env1/bin/python
Installing distribute.............................................
..................................................................
..................................................................
done.
(env1)$ mkvirtualenv env2
New python executable in env2/bin/python
Installing distribute.............................................
..................................................................
..................................................................
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)$

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 distribute.............................................
..................................................................
..................................................................
done.
(env1)$ echo $VIRTUAL_ENV
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env1
(env1)$ deactivate
$ echo $VIRTUAL_ENV

$

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 distribute.............................................
..................................................................
..................................................................
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 distribute.............................................
..................................................................
..................................................................
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 distribute.............................................
..................................................................
..................................................................
done.
(env1)$ $ workon env1
(env1)$ lssitepackages
distribute-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-pacakges 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.

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.