Python Language Virtual environments Creating and using a virtual environment
Example
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/activate_this.py'
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/activate_this.py 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 activate_this.py 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
or
$ python3 -m venv foo
$ source foo/bin/activate
