The concept of virtual environments was new to me when I started learning about python, so I wanted to document the key concepts/examples that I used regarding virtual environments.  The tipping point for me with virtual environments was when I developed a project using python 2.7, as one of the key packages that I was using could only be run under python 2.x.  However, I wanted to use python 3.x (latest and greatest, right?) for my other python projects.  Virtual environments solve this problem perfectly.

Install and Configure “virtualenv” and “virtualenvwrapper”

The python packages “virtualenv” and “virtualenvwrapper” should be installed using pip (and potentially prefix with ‘sudo’ if you need admin rights to install on your system):

$ pip install virtualenv
$ pip install virtualenvwrapper

Next, create a folder that will contain all your virtual environments:

$ mkdir ~/.virtualenvs

Open your .bashrc file and set the virtual environment directory and source the script for the virtual environment package:

export WORKON_HOME=~/.virtualenvs
source /usr/local/bin/

If you want to continue working in your current terminal window, you can activate these changes by typing:

$ source ~/.bashrc

Remember to source this file any time you open a new terminal.

Creating a New Virtual Environment

In your development workspace, create a new directory:

$ mkdir new_python_project

Typically, the command ‘python’ will be associated with a python 2.x installation, but ‘python3’ will be associated with a python 3.x installation. If you want to use python 3.x in your virtual environment, then you’ll need to include the path to your python 3.x installation. If you’re using python 2.x, then just omit specifying the path to your python installation (the virtual environment will default to the python installation in your system configuration).

To start, determine the path for your installation of python3:

$ which python3

Create the virtual environment using ‘virtualenvwrapper’ and include the path for your python3 installation as a flag:

$ mkvirtualenv --python=<PYTHON_PATH> py_env

Here is the output that you should see when you create the virtual environment:

$ which python3

$ mkvirtualenv --python=/Library/Frameworks/Python.framework/Versions/3.4/bin/python3 web_sc
Running virtualenv with interpreter /Library/Frameworks/Python.framework/Versions/3.4/bin/python3
Using base prefix '/Library/Frameworks/Python.framework/Versions/3.4'
New python executable in web_sc/bin/python3
Also creating executable in web_sc/bin/python
Installing setuptools, pip, wheel...done.

NOTE: I recommend keeping the name of the virtual environment relatively short in length, as this name will show up to the left of your comment prompt when you are working in the virtual environment.

You can see that this command created a directory in your virtual environments folder:

$ ls –l ~/.virtualenvs/
drwxr-xr-x 6 patrick staff 204 Aug 21 02:50 web_sc

You can now start working on your new python project.  In this example, python3 was set as the version of python to use, so running ‘python ’ will utilize python3.  You don’t need to run ‘python3 ’!

Let’s double-check that we’re actually using python3 in the virtual environment:

(web_sc)$ python --version
Python 3.4.3

Activating and Deactivating a Virtual Environment

If you are working in a virtual environment, you should see the name of the virtual environment to the left of your command prompt:

(web_sc)$ python --version
Python 3.4.3

To deactivate the virtual environment:

(web_sc)$ deactivate

To activate a specific virtual environment (for example, the one that is created in the previous section):

$ workon web_sc

To see a list of the virtual environments that your have created:

$ lsvirtualenv

To delete a virtual environment that you are no longer using:

$ rmvirtualenv web_sc

Installing Python packages in your virtual environment

Before installing any packages in your virtual environment, make sure your virtual environment is activated.  You should see the name of your virtual environment to the left of your command prompt:


If you don’t see the name of your virtual environment to the left of your command prompt, then you need to activate your specific virtual environment (for example, the one that is created in the previous section):

$ workon web_sc

You can now install python packages that will be just used in your virtual environment.  If you want to install the the Django web framework, you type:

(web_sc)$ pip install Django

NOTE: you don’t need to include sudo when installing packages in a virtual environment!

Logging the Packages used in a Virtual Environment

After you have installed the packages that you think you’ll need, it is a good practice to log the packages used (plus the specific versions) within the virtual environment:

(web_sc)$ pip freeze > requirements.txt

This creates a file called ‘requirements.txt’ that you should always include in your project, especially within the repository for your project.  This file is very convenient, as it allows other users to easily set up the same environment that you have by typing:

(web_sc)$ pip install -r requirements.txt