Python Language Virtual environments Creating and using a virtual environment


virtualenv is a tool to build isolated Python environments. This program creates a folder which contains all the necessary executables to use the packages that a Python project would need.

Installing the virtualenv tool

This is only required once. The virtualenv program may be available through your distribution. On Debian-like distributions, the package is called python-virtualenv or python3-virtualenv.

You can alternatively install virtualenv using pip:

$ pip install virtualenv

Creating a new virtual environment

This only required once per project. When starting a project for which you want to isolate dependencies, you can setup a new virtual environment for this project:

$ virtualenv foo

This will create a foo folder containing tooling scripts and a copy of the python binary itself. The name of the folder is not relevant. Once the virtual environment is created, it is self-contained and does not require further manipulation with the virtualenv tool. You can now start using the virtual environment.

Activating an existing virtual environment

To activate a virtual environment, some shell magic is required so your Python is the one inside foo instead of the system one. This is the purpose of the activate file, that you must source into your current shell:

$ source foo/bin/activate

Windows users should type:

$ foo\Scripts\activate.bat

Once a virtual environment has been activated, the python and pip binaries and all scripts installed by third party modules are the ones inside foo. Particularly, all modules installed with pip will be deployed to the virtual environment, allowing for a contained development environment. Activating the virtual environment should also add a prefix to your prompt as seen in the following commands.

# Installs 'requests' to foo only, not globally
(foo)$ pip install requests

Saving and restoring dependencies

To save the modules that you have installed via pip, you can list all of those modules (and the corresponding versions) into a text file by using the freeze command. This allows others to quickly install the Python modules needed for the application by using the install command. The conventional name for such a file is requirements.txt:

(foo)$ pip freeze > requirements.txt
(foo)$ pip install -r requirements.txt

Please note that freeze lists all the modules, including the transitive dependencies required by the top-level modules you installed manually. As such, you may prefer to craft the requirements.txt file by hand, by putting only the top-level modules you need.

Exiting a virtual environment

If you are done working in the virtual environment, you can deactivate it to get back to your normal shell:

(foo)$ deactivate

Using a virtual environment in a shared host

Sometimes it's not possible to $ source bin/activate a virtualenv, for example if you are using mod_wsgi in shared host or if you don't have access to a file system, like in Amazon API Gateway, or Google AppEngine. For those cases you can deploy the libraries you installed in your local virtualenv and patch your sys.path.

Luckly virtualenv ships with a script that updates both your sys.path and your sys.prefix

import os

mydir = os.path.dirname(os.path.realpath(__file__))
activate_this = mydir + '/bin/'
execfile(activate_this, dict(__file__=activate_this))

You should append these lines at the very beginning of the file your server will execute.

This will find the bin/ that virtualenv created file in the same dir you are executing and add your lib/python2.7/site-packages to sys.path

If you are looking to use the script, remember to deploy with, at least, the bin and lib/python2.7/site-packages directories and their content.

Python 3.x3.3

Built-in virtual environments

From Python 3.3 onwards, the venv module will create virtual environments. The pyvenv command does not need installing separately:

$ pyvenv foo
$ source foo/bin/activate


$ python3 -m venv foo
$ source foo/bin/activate