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.
This is only required once. The
virtualenv program may be available through your distribution. On Debian-like distributions, the package is called
You can alternatively install
virtualenv using pip:
$ pip install virtualenv
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.
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:
Once a virtual environment has been activated, the
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
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
(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.
If you are done working in the virtual environment, you can deactivate it to get back to your normal shell:
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
Luckly virtualenv ships with a script that updates both your
sys.path and your
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
virtualenv created file in the same dir you are executing and add your
If you are looking to use the
activate_this.py script, remember to deploy with, at least, the
lib/python2.7/site-packages directories and their content.
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