virtualenv

virtualenvwrapper is not file based (it depends heavily on workon). And it's setup is not very easy. While virtualenv can be used like npm (one virtual env in one project). So I prefer virtualenv to virturalenvwrapper for managing Python project environment.

Install it with sudo pip install virtualenv.

Workflow with virtualenv:

1. In a Python project root folder, run virtualenv venv to build the home folder for virtual environment, and add venv into .gitignore.

2. Run . venv/bin/activate to activate the environment;

3. pip install -r requirements.txt to install dependent packages;

4. Edit files and test project with python ...;

5. Quit environment with deactivate;

Note:

Add -p <python-bin-path> to use alternative Python executable. For example, virtualenv -p /usr/bin/python3 venv to build an environment using Python 3.

virturalenvwrapper

Installation

$ sudo pip install virtualenvwrapper

Add the following lines into ~/.zshenv:

WORKON_HOME=~/docs/workspace/python-workspace/env-home
PROJECT_HOME=~/docs/workspace/python-workspace/project-home

and create the two folders specified above.

Add following lines into ~/.zshrc:

source /usr/local/bin/virtualenvwrapper.sh

Usage

For new project

Create a new project funcPy using Python 3.x (run in any foler):

mkproject -p /usr/bin/python3 funcPy

The CWD will be changed into the project root automatically.

Verify:

$ python -V
Python 3.4.3
$ deactivate
$ python -V
Python 2.7.6

Coming into the project root and virtualenv later: workon funcPy. Use key to autocomplete after workon.

If using the default Python version (in Ubuntu 14.04 it is 2.7) for your virtual environment, create the project with mkproject funcPy.

To debug this project in PyCharm, open the project in PyCharm (get the project root folder with workon funcPy && echo $PWD). In [File -> Settings -> Project: funcPy -> Project Interpreter], press the gear button on the right side of "Project Interpreter", choose "Add Local", select the python executable in the corresponding virtualenv folder (get it with cdvirtualenv && echo $PWD/bin/python).

The python intepreter config is persisted in PyCharm project configuration, so no need to use workon every time open the project in PyCharm.

See Adding Existing Virtual Environment in PyCharm 2016.1 Help for reference.

Note:

If the script has command line arguments, add them in [Run -> Edit Configurations -> Script parameters].

For existing project

git clone git@github.com:mbr/flask-bootstrap.git
cd flask-bootstrap
mkvirtualenv flask-bootstrap
setvirtualenvproject
cd sample_app
pip install -r requirements.txt
mkvirtualenv testenv2
setvirtualenvproject

Now there are 2 virtualenvs: flask-bootstrap and testenv2 are associated with project flask-bootstrap. If you input workon and press TAB, you can see both these 2 virtualenvs. No matter which one you choose, you will be transmitted to the root folder of project flask-bootstrap.

Note: use rmvirtualenv testenv2 to remove a virtualenv.

Discussion

There are two concepts in virturalenvwrapper. One is "virtual environment", which has its own python executables. The other is "project", where your source codes resides. They are n-to-1 relationship. If you specify a project-virtualenv relation with setvirtualenvproject path-to-project-A path-to-env-X, while the virtualenv X already has associated to project B, the new project A will replace the old project B.

Why not use the same folder for both project and environment, like npm?

Reason 1: A project can associate with many virtualenvs (through setvirtualenvproject), so for example you can test your application under Python 2 and 3 in difference virtual environments.

Reason 2: Unlike the "node_modules" folder in a node.js project, Python project can't put packages directly into the source folder. Use pip install the-package && pip freeze > requirements.txt to install a package and save it into dependency document, like npm install the-package --save. Activate you virtual env and use pip install -r requirements.txt to install all dependencies into the virtual environment.

"mkvirtualenv env1" will create a new "virtual environment" in $WORKON_HOME, regardless your CWD.

"mkproject proj1" will create both a "virtual environment" named "proj1" in $WORKON_HOME and a "proj1" folder in $PROJECT_HOME. Then go to $PROJECT_HOME/proj1, and activate the virtual environment proj1. So "mkproject proj1" equals to:

$ mkvirtualenv proj1
$ mkdir $PROJECT_HOME/proj1
$ cd $PROJECT_HOME/proj1
$ workon proj1

Associate an existing virtualenv and an existing project with command

$ setvirtualenvproject virtualenv_path project_path

Under the hood, virturalenvwrapper create a ".project" file under the root of the virtualenv, in which is the project path.

List site packages:

$ lssitepackages

Run a command in all virtualenvs under WORKON_HOME:

$ allvirtualenv command with arguments

Change the current working directory to the site-packages of current virtualenv($VIRTUAL_ENV):

$ cdsitepackages

Remove virtualenv:

$ rmvirtualenv <env_name>

Verification

In a virtualenv, all python executables are in $WORKON_HOME.

[lichao@lichao480:~] 
$ workon 
env1 env2 proj1 
[lichao@lichao480:~] 
$ which python 
/usr/bin/python 
[lichao@lichao480:~] 
$ workon env1 
(env1)[lichao@lichao480:~] 
$ which python 
/home/lichao/apps/virenv_home/env1/bin/python 
(env1)[lichao@lichao480:~] 
$ workon env2 
(env2)[lichao@lichao480:~PROJECT_HOME/proj2] 
$ which python 
/home/lichao/apps/virenv_home/env2/bin/python