Python Projects Isolation Using Virtual Environments

Project isolation

Last modified:
Tags Virtual-Environments , Virtualenv , Python , Packages , Versioning


The tipical workflow to isolate a python project consist of the following steps:

  1. Create a project dir
  2. Create a virtual environment for the project outside its directory structure
  • virtualenvwrapper uses the variable WORKON_HOME to specify the location of new virtual environments. The default value is $HOME/.virtualenvs

Then each time you work on the project you have two alternatives:

  • Manually:

    • Manually create and activate the virtual environment for the project
      • Create an instance where all the packages are installed for a specific project instead of executing those present in the Operating System, then you will need to active it each time you work in that project.
      • source ~/.virtualenvs/my_project/bin/activate
  • Automatic:

    • Configure a virtualenvwrapper
      • it provides often used processes as scripts and defines standard environment variables and installation paths.
      • Using it is as easy as select your environment with a command
        • workon my_project


Create a virtual environment

Create the virtual environment (preferable in a directory outside the project)

The preferred python version to use in the new environment can also be specified.

#Create the project
$ mkdir my_project;
#Create the virtual environment
$ virtualenv -p python3.5 ~/.virtualenvs/my_project

Use the virtual environment

To use the new environment, it should be activated. Any command executed after activating it, will use the packages installed in this virtual environment.

Console prompt will change (in most cases) to reflect this situation prepending the virtual environment name in terminal prompt.

$ source ~/.virtualenvs/my_project/bin/activate

Stop using the virtual environment

(virtualenv)$ deactivate



Virtualenvwrapper makes it easier to perform virtualenv tasks. It is build upon the following concepts:

  • Projects
  • The source code that needs a special virtual environment specified in a requirements file.
  • The base directory for projects is specified in PROJECT_HOME.
  • A Virtualenv directory
    • All the virtualenvs for each project will be contained here in subdirectories.
    • Specified in the variable WORKON_HOME, by default will be: $HOME/.virtualenvs

mkvirtualenv provides the same options as virtualenv plus a few options. It creates by default the virtualenv environment in ~/.virtualenvs/<env_name> and then activates it.

Usage: mkvirtualenv [-a project_path] [-i package] [-r requirements_file] [virtualenv options] env_name

virtualenvwrapper workflow

Common workflow to work on a new virtual environment using virtualenvwrapper:

In Ubuntu it can be installed with sudo apt-get install virtualenvwrapper
  • Create the virtual environment

    • (by default it will available in $WORKON_HOME)

    The variable WORKON_HOME tells virtualenvwrapper where to place your > virtual environments. The default is $HOME/.virtualenvs. If the directory does not exist when virtualenvwrapper is loaded, it will be created automatically.

  • list the available environments and activate the project to work on with workon

  • Go to the project directory cdvirtualenv

  • deactivate the environment when finished working

$ mkvirtualenv myenvname
New python executable in /home/marcanuy/.virtualenvs/myenvname/bin/python
Installing setuptools, pip, wheel...done.
#the previous created env will appear listed, along the other envs
(myenvname)$ workon
#changes to the associated project directory
(myenvname)$ cdvirtualenv myenvname
(myenvname)/opt/development/myproject$ cdsitepackages
(myenvname)~/.virtualenvs/myenvname/lib/python3.5/site-packages$ cdvirtualenv
#finish work
(myenvname)/opt/development/myproject$ deactivate
/opt/development/myproject$ _

To create a new environment having a requirements file and a specific python version: mkvirtualenv -r requirements/local.txt -p /usr/bin/python3.5 myprojectname

Other alternatives


Marcelo Canina
I'm Marcelo Canina, a developer from Uruguay. I build websites and web-based applications from the ground up and share what I learn here.
comments powered by Disqus

Handle dependencies and app versions for each project with python virtual environments.

Clutter-free software concepts.
Translations English Espa簽ol

Except as otherwise noted, the content of this page is licensed under CC BY-NC-ND 4.0 . Terms and Policy.

Powered by SimpleIT Hugo Theme