Python Virtualenv Tutorial

The headaches of dependency management are common to developers. One errant update requires hours of research to correct.  Often multiple applications overlap on library dependency requirements.  This could cause two applications running in the same environment to require two version of the same library.  These type of conflicts could cause a number of issues both in development and production.Enter Virtualenv.  Virtualenv is a tool that creates dependency silos.  It allows you to deploy applications to a single environment with isolated dependencies. Docker employs a similar strategy at the OS level. Virtualenv segregates only at the Python and library level — that is, the environments Python executable and libraries are unique to that virtual environment.  So instead of using the libraries installed at the OS environment level, you can separate Python versions and libraries into siloed virtual environments.  This allows you to deploy multiple applications in the same OS environment with different versions of the same dependencies.

Install Virtualenv

The install of Virtualenv is straight forward. Using pip, you can execute the below command from the terminal.

$ pip install virtualenv

Alternatively, if using Anaconda you will need to use the below terminal command instead.

$ conda install virtualenv

Your terminal output should look similar to the below.

Bradleys-Mini:~ BradleyPatton$ pip install virtualenv
Collecting virtualenv
Downloading virtualenv-15.1.0-py2.py3-none-any.whl (1.8MB)
100% |████████████████████████████████| 1.8MB 267kB/s
Installing collected packages: virtualenv
Successfully installed virtualenv-15.1.0
Bradleys-Mini:~ BradleyPatton$

Create an Environment

Virtualenv has one main command. The below line executed from the terminal will create a new “silo” or virtual Python environment in the Tutorial directory.

$ virtualenv Tutorial

You should get some terminal output like below after executing.

Bradleys-Mini:site-packages BradleyPatton$ virtualenv Tutorial
Overwriting /Users/BradleyPatton/anaconda/lib/python2.7/site-
packages/Tutorial/lib/python2.7/orig-prefix.txt with new content
New python executable in /Users/BradleyPatton/anaconda/lib/python2.7/site-
copying /Users/BradleyPatton/anaconda/bin/python =>
copying /Users/BradleyPatton/anaconda/bin/../lib/libpython2.7.dylib =>
Installing setuptools, pip, wheel...done.

The virtualenv command will build a directory structure including a binary, library and include directory for the new virtual environment that was created.

Bradleys-Mini:Tutorial BradleyPatton$ ls
bin                            lib
include                        pip-selfcheck.json
Bradleys-Mini:Tutorial BradleyPatton$

/bin contains your executables most notably Python and pip.

Bradleys-Mini:bin BradleyPatton$ ls
activate                    easy_install-2.7           python-config
activate.csh                pip                        python2               pip2                        python2.7           pip2.7                       wheel
easy_install                 python
Bradleys-Mini:bin BradleyPatton$

The /lib and /include directories include supporting files for Python and the application to be developed.

Activate Virtualenv

The activation script updates your path so that you can utilize this virtual environment without the hassle of navigating to the directory. It makes it a bit easier to use, but could be skipped if you are a terminal ninja and don’t mind the key strokes.

In the /bin directory there is an activate BASH script. You can execute using the below.

$ ./activate

If you will note from my fumbling below that I had to modify the permission of the file to execute. I used the CHMOD 700 activate command to update the permissions. You may also need to make this update prior to running the activate script.

Bradleys-Mini:bin BradleyPatton$ ls
activate              easy_install-2.7     python-config
activate.csh           pip                  python2          pip2                 python2.7       pip2.7                wheel
easy_install           python
Bradleys-Mini:bin BradleyPatton$ ./activate
-bash: ./activate: Permission denied
Bradleys-Mini:bin BradleyPatton$ sudo ./activate
sudo: ./activate: command not found
Bradleys-Mini:bin BradleyPatton$ chmod 700 activate
Bradleys-Mini:bin BradleyPatton$ ./activate
Bradleys-Mini:bin BradleyPatton$

Deactivate Virtualenv

To undo the environment variable changes that were made by activate run the following command from the terminal. This will revert your path changes like they never happened. It’s as simple as that.

$ deactivate

Removing an Environment

Removing a virtual environment is as simple as rm. Simply type the following to remove the directory and recursively its contents.

$ rm -r TutorialtoRemove

Now What

Well, now you need to install your libraries and application in the new virtual environment.  Pip makes sourcing your libraries easy.

I won’t go into the subtleties of pip some of which can be found here, but I will demonstrate a single pip install.

$ pip install pandas


(Tutorial) Bradleys-Mini:bin BradleyPatton$ pip install pandas
Collecting pandas
Using cached pandas-0.22.0-cp27-cp27m-macosx_10_6_intel.macosx_10_9_intel.macosx_10_9
Collecting numpy>=1.9.0 (from pandas)
Using cached numpy-1.14.0-cp27-cp27m-macosx_10_6_intel.macosx_10_9_intel.macosx_10_9
Collecting python-dateutil (from pandas)
Using cached python_dateutil-2.6.1-py2.py3-none-any.whl
Collecting pytz>=2011k (from pandas)
Using cached pytz-2017.3-py2.py3-none-any.whl
Collecting six>=1.5 (from python-dateutil->pandas)
Using cached six-1.11.0-py2.py3-none-any.whl
Installing collected packages: numpy, six, python-dateutil, pytz, pandas
Successfully installed numpy-1.14.0 pandas-0.22.0
python-dateutil-2.6.1 pytz-2017.3 six-1.11.0
(Tutorial) Bradleys-Mini:bin BradleyPatton$

The following command will open a Python interpreter command line.  I will import our new pandas library and check the version. Version 19 is my global pandas version, but as you see from the terminal output, the version used in our Tutorial virtual environement is 22.

$ python
(Tutorial) Bradleys-Mini:bin BradleyPatton$ python
Python 2.7.13 |Continuum Analytics, Inc.| (default, Dec 20 2016, 23:05:08)
[GCC 4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.57)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
Anaconda is brought to you by Continuum Analytics.
Please check out: and
>>> import pandas
>>> pandas.__version__

This tutorial should get you started with Virtualenv.  I have added the link to the Virtualenv page that can assist with some in depth configuration using parameters and configuration settings that can be used in special circumstances.


About the author


Brad Patton

Brad Patton is a software engineering consultant and writer who delivers high quality software systems to his clients. He received his undergraduate and graduate degree in Computer Science. Brad leverages his expertise in programming and mathematics to develop profitable algorithmic trading strategies. He shares his experience by writing about his tools and strategies. He can be found on Twitter at @BradleyPatton.