Virtualenwrapper

1. Introduction

Virtualenvwrapper is a set of extensions to Ian Bicking’s virtualenv tool. The extensions include wrappers for creating and deleting virtual environments and otherwise managing your development workflow, making it easier to work on more than one project at a time without introducing conflicts in their dependencies.

2. Installation

$ sudo pip install virtualenvwrapper

$ vim ~/.bashrc
    # add three lines
    export WORKON_HOME=$HOME/.virtualenvs
    export PROJECT_HOME=$HOME/Projects/Python
    source /usr/local/bin/virtualenvwrapper.sh
$ source ~/.bashrc

3. Command

3.1 mkvirtualenv

Create a new environment, in the WORKON_HOME.

mkvirtualenv [-a project_path] [-i package] [-r requirements_file] [virtualenv options] ENVNAME
# -a: associate an existing project directory with the new environment.
# -i: install one or more packages after the environment is created.
# -r: specify a text file listing packages to be installed.

3.2 mktmpenv

Create a new temporary virtualenv in the WORKON_HOME directory. A unique virtualenv name is generated.

mktmpenv [(-c|--cd)|(-n|--no-cd)] [VIRTUALENV_OPTIONS]

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.

3.3 lsvirtualenv

List all of the environments.

lsvirtualenv [-b] [-l] [-h]
# -b: Brief mode, disables verbose output.
# -l: Long mode, enables verbose output. Default.
# -h: Print the help for lsvirtualenv.

3.4 showvirtualenv

Show the details for a single virtualenv.

showvirtualenv [env]

3.5 rmvirtualenv

Remove an environment, in the WORKON_HOME.

rmvirtualenv ENVNAME

3.6 cpvirtualenv

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

cpvirtualenv ENVNAME [TARGETENVNAME]

3.7 allvirtualenv

Run a command in all virtualenvs under WORKON_HOME.

allvirtualenv command with arguments

3.8 workon

List or change working virtual environments

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 .

3.9 deactivate

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

deactivate

3.10 mkproject

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

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. 

3.11 setvirtualenvproject

Bind an existing virtualenv to an existing project.

setvirtualenvproject [virtualenv_path project_path]

3.12 cdproject

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

cdproject

3.13 wipeenv

Remove all of the installed third-party packages in the current virtualenv.

wipeenv

4. Examples

4.1 set python version

mkvirtualenv --python=/usr/bin/python3 ENVNAME
mkproject --python=/usr/bin/python3 ENVNAME