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
$ 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:

$ pip freeze > requirements.txt
$ 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.