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:

  1. mkvirtualenv [-a project_path] [-i package] [-r requirements_file] [virtualenv options] ENVNAME

All command line options except -a, -i, -r, and -h are passeddirectly to virtualenv. The new environment is automaticallyactivated after being initialized.

  1. $ workon
  2. $ mkvirtualenv mynewenv
  3. New python executable in mynewenv/bin/python
  4. Installing setuptools.............................................
  5. ..................................................................
  6. ..................................................................
  7. done.
  8. (mynewenv)$ workon
  9. mynewenv
  10. (mynewenv)$

The -a option can be used to associate an existing projectdirectory with the new environment.

The -i option can be used to install one or more packages (byrepeating the option) after the environment is created.

The -r option can be used to specify a text file listing packagesto be installed. The argument value is passed to pip -r to beinstalled.

See also

mktmpenv

Create a new virtualenv in the WORKON_HOME directory.

Syntax:

  1. 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 tothe virtualenv directory during the post-activate phase, regardless ofthe value of VIRTUALENVWRAPPER_WORKON_CD.

If -n or —no-cd is specified the working directory is notchanged to the virtualenv directory during the post-activate phase,regardless of the value of VIRTUALENVWRAPPER_WORKON_CD.

  1. $ mktmpenv
  2. Using real prefix '/Library/Frameworks/Python.framework/Versions/2.7'
  3. New python executable in 1e513ac6-616e-4d56-9aa5-9d0a3b305e20/bin/python
  4. Overwriting 1e513ac6-616e-4d56-9aa5-9d0a3b305e20/lib/python2.7/distutils/__init__.py
  5. with new content
  6. Installing setuptools...............................................
  7. ....................................................................
  8. .................................................................done.
  9. This is a temporary environment. It will be deleted when deactivated.
  10. (1e513ac6-616e-4d56-9aa5-9d0a3b305e20) $

lsvirtualenv

List all of the environments.

Syntax:

  1. lsvirtualenv [-b] [-l] [-h]
-bBrief mode, disables verbose output.
-lLong mode, enables verbose output. Default.
-hPrint the help for lsvirtualenv.

See also

showvirtualenv

Show the details for a single virtualenv.

Syntax:

  1. showvirtualenv [env]

See also

rmvirtualenv

Remove an environment, in the WORKON_HOME.

Syntax:

  1. rmvirtualenv ENVNAME

You must use deactivate before removing the currentenvironment.

  1. (mynewenv)$ deactivate
  2. $ rmvirtualenv mynewenv
  3. $ workon
  4. $

See also

cpvirtualenv

Duplicate an existing virtualenv environment. The source can be anenvironment managed by virtualenvwrapper or an external environmentcreated elsewhere.

Warning

Copying virtual environments is not well supported. Each virtualenvhas path information hard-coded into it, and there may be caseswhere the copy code does not know it needs to update a particularfile. Use with caution.

Syntax:

  1. cpvirtualenv ENVNAME [TARGETENVNAME]

Note

Target environment name is required for WORKON_HOMEduplications. However, target environment name can be ommited forimporting external environments. If omitted, the new environment isgiven the same name as the original.

  1. $ workon
  2. $ mkvirtualenv source
  3. New python executable in source/bin/python
  4. Installing setuptools.............................................
  5. ..................................................................
  6. ..................................................................
  7. done.
  8. (source)$ cpvirtualenv source dest
  9. Making script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/easy_install relative
  10. Making script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/easy_install-2.6 relative
  11. Making script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/pip relative
  12. 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)
  13. 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)
  14. 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)
  15. 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)
  16. (dest)$ workon
  17. dest
  18. source
  19. (dest)$

See also

allvirtualenv

Run a command in all virtualenvs under WORKON_HOME.

Syntax:

  1. allvirtualenv command with arguments

Each virtualenv is activated, bypassing activation hooks, the currentworking directory is changed to the current virtualenv, and then thecommand is run. Commands cannot modify the current shell state, butcan modify the virtualenv.

  1. $ allvirtualenv pip install -U pip

Controlling the Active Environment

workon

List or change working virtual environments

Syntax:

  1. workon [(-c|--cd)|(-n|--no-cd)] [environment_name|"."]

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

If -c or —cd is specified the working directory is changed tothe project directory during the post-activate phase, regardless ofthe value of VIRTUALENVWRAPPER_WORKON_CD.

If -n or —no-cd is specified the working directory is notchanged 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 fromthe base name of the current working directory (contributed by MatiasSaguir).

  1. $ workon
  2. $ mkvirtualenv env1
  3.   New python executable in env1/bin/python
  4. Installing setuptools.............................................
  5. ..................................................................
  6. ..................................................................
  7. done.
  8. (env1)$ mkvirtualenv env2
  9. New python executable in env2/bin/python
  10. Installing setuptools.............................................
  11. ..................................................................
  12. ..................................................................
  13. done.
  14. (env2)$ workon
  15. env1
  16. env2
  17. (env2)$ workon env1
  18. (env1)$ echo $VIRTUAL_ENV
  19. /Users/dhellmann/Devel/virtualenvwrapper/tmp/env1
  20. (env1)$ workon env2
  21. (env2)$ echo $VIRTUAL_ENV
  22. /Users/dhellmann/Devel/virtualenvwrapper/tmp/env2
  23. (env2)$

See also

deactivate

Switch from a virtual environment to the system-installed version ofPython.

Syntax:

  1. deactivate

Note

This command is actually part of virtualenv, but is wrapped toprovide before and after hooks, just as workon does for activate.

  1. $ workon
  2. $ echo $VIRTUAL_ENV
  3.  
  4. $ mkvirtualenv env1
  5. New python executable in env1/bin/python
  6. Installing setuptools.............................................
  7. ..................................................................
  8. ..................................................................
  9. done.
  10. (env1)$ echo $VIRTUAL_ENV
  11. /Users/dhellmann/Devel/virtualenvwrapper/tmp/env1
  12. (env1)$ deactivate
  13. $ echo $VIRTUAL_ENV
  14.  
  15. $

See also

Quickly Navigating to a virtualenv

There are two functions to provide shortcuts to navigate into thecurrently-active virtualenv.

cdvirtualenv

Change the current working directory to $VIRTUAL_ENV.

Syntax:

  1. cdvirtualenv [subdir]

Calling cdvirtualenv changes the current working directory to thetop of the virtualenv ($VIRTUAL_ENV). An optional argument isappended to the path, allowing navigation directly into asubdirectory.

  1. $ mkvirtualenv env1
  2. New python executable in env1/bin/python
  3. Installing setuptools.............................................
  4. ..................................................................
  5. ..................................................................
  6. done.
  7. (env1)$ echo $VIRTUAL_ENV
  8. /Users/dhellmann/Devel/virtualenvwrapper/tmp/env1
  9. (env1)$ cdvirtualenv
  10. (env1)$ pwd
  11. /Users/dhellmann/Devel/virtualenvwrapper/tmp/env1
  12. (env1)$ cdvirtualenv bin
  13. (env1)$ pwd
  14. /Users/dhellmann/Devel/virtualenvwrapper/tmp/env1/bin

cdsitepackages

Change the current working directory to the site-packages for$VIRTUAL_ENV.

Syntax:

  1. cdsitepackages [subdir]

Because the exact path to the site-packages directory in thevirtualenv depends on the version of Python, cdsitepackages isprovided as a shortcut for cdvirtualenvlib/python${pyvers}/site-packages. An optional argument is alsoallowed, to specify a directory hierarchy within the site-packagesdirectory to change into.

  1. $ mkvirtualenv env1
  2. New python executable in env1/bin/python
  3. Installing setuptools.............................................
  4. ..................................................................
  5. ..................................................................
  6. done.
  7. (env1)$ echo $VIRTUAL_ENV
  8. /Users/dhellmann/Devel/virtualenvwrapper/tmp/env1
  9. (env1)$ cdsitepackages PyMOTW/bisect/
  10. (env1)$ pwd
  11. /Users/dhellmann/Devel/virtualenvwrapper/tmp/env1/lib/python2.6/site-packages/PyMOTW/bisect

lssitepackages

Calling lssitepackages shows the content of the site-packagesdirectory of the currently-active virtualenv.

Syntax:

  1. lssitepackages
  1. $ mkvirtualenv env1
  2. New python executable in env1/bin/python
  3. Installing setuptools.............................................
  4. ..................................................................
  5. ..................................................................
  6. done.
  7. (env1)$ $ workon env1
  8. (env1)$ lssitepackages
  9. setuptools-0.6.10-py2.6.egg     pip-0.6.3-py2.6.egg
  10. easy-install.pth                setuptools.pth

Path Management

add2virtualenv

Adds the specified directories to the Python path for thecurrently-active virtualenv.

Syntax:

  1. add2virtualenv directory1 directory2 ...

Sometimes it is desirable to share installed packages that are not inthe system site-packages directory and which should not beinstalled in each virtualenv. One possible solution is to symlink thesource into the environment site-packages directory, but it isalso easy to add extra directories to the PYTHONPATH by including themin a .pth file inside site-packages using add2virtualenv.

  • Check out the source for a big project, such as Django.
  • Run: add2virtualenv path_to_source.
  • Run: add2virtualenv.
  • A usage message and list of current “extra” paths is printed.
  • 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 directoryfor the environment.

Based on a contribution from James Bennett and Jannis Leidel.

toggleglobalsitepackages

Controls whether the active virtualenv will access the packages in theglobal Python site-packages directory.

Syntax:

  1. toggleglobalsitepackages [-q]

Outputs the new state of the virtualenv. Use the -q switch to turn off alloutput.

  1. $ mkvirtualenv env1
  2. New python executable in env1/bin/python
  3. Installing setuptools.............................................
  4. ..................................................................
  5. ..................................................................
  6. done.
  7. (env1)$ toggleglobalsitepackages
  8. Disabled global site-packages
  9. (env1)$ toggleglobalsitepackages
  10. Enabled global site-packages
  11. (env1)$ toggleglobalsitepackages -q
  12. (env1)$

Project Directory Management

See also

Project Management

mkproject

Create a new virtualenv in the WORKON_HOME and project directory inPROJECT_HOME.

Syntax:

  1. mkproject [-f|--force] [-t template] [virtualenv_options] ENVNAME
-f, —forceCreate the virtualenv even if the project directoryalready exists

The template option may be repeated to have several templates used tocreate a new project. The templates are applied in the order named onthe command line. All other options are passed to mkvirtualenv tocreate a virtual environment with the same name as the project.

  1. $ mkproject myproj
  2. New python executable in myproj/bin/python
  3. Installing setuptools.............................................
  4. ..................................................................
  5. ..................................................................
  6. done.
  7. Creating /Users/dhellmann/Devel/myproj
  8. (myproj)$ pwd
  9. /Users/dhellmann/Devel/myproj
  10. (myproj)$ echo $VIRTUAL_ENV
  11. /Users/dhellmann/Envs/myproj
  12. (myproj)$

See also

setvirtualenvproject

Bind an existing virtualenv to an existing project.

Syntax:

  1. setvirtualenvproject [virtualenv_path project_path]

The arguments to setvirtualenvproject are the full paths to thevirtualenv and project directory. An association is made so that whenworkon activates the virtualenv the project is also activated.

  1. $ mkproject myproj
  2. New python executable in myproj/bin/python
  3. Installing setuptools.............................................
  4. ..................................................................
  5. ..................................................................
  6. done.
  7. Creating /Users/dhellmann/Devel/myproj
  8. (myproj)$ mkvirtualenv myproj_new_libs
  9. New python executable in myproj/bin/python
  10. Installing setuptools.............................................
  11. ..................................................................
  12. ..................................................................
  13. done.
  14. Creating /Users/dhellmann/Devel/myproj
  15. (myproj_new_libs)$ setvirtualenvproject $VIRTUAL_ENV $(pwd)

When no arguments are given, the current virtualenv and currentdirectory are assumed.

Any number of virtualenvs can refer to the same project directory,making it easy to switch between versions of Python or otherdependencies for testing.

cdproject

Change the current working directory to the one specified as theproject directory for the active virtualenv.

Syntax:

  1. cdproject

Managing Installed Packages

wipeenv

Remove all of the installed third-party packages in the currentvirtualenv.

Syntax:

  1. wipeenv

Other Commands

virtualenvwrapper

Print a list of commands and their descriptions as basic help output.

Syntax:

  1. virtualenvwrapper