Source

virtualenvwrapper / docs / en / command_ref.rst

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 [-l] [-h]
-l Long mode, enables verbose output.
-h Print the help for lsvirtualenv.

rmvirtualenv

Remove an environment, in the WORKON_HOME.

Syntax:

rmvirtualenv ENVNAME

You must use :ref:`command-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.