How to install Python dependencies in a project

To install dependencies in a project, you must first List your dependencies, then Process the list. Both steps are described below.

List your dependencies

Your Divio project has a file, processed by the pip-compile command from pip-tools when the project is built.

Place your dependencies in the file, making sure that they are outside the:



tags, since that part of the file is maintained automatically and is overwritten automatically with the requirements from the Addons system.

Wherever possible, pin your dependencies

An unpinned dependency is a hostage to fortune, and is highly likely to break something without warning when a new release is made.

Unpinned dependencies are the number one cause of deployment failures. Nothing in the codebase may have changed, but a fresh deployment can unexpectedly pick up a newly-released version of a package.

When installing from a version control repository, it is strongly recommended to pin the package by specifying a tag or commit, rather than branch.

Sometimes your dependencies may themselves have unpinned dependencies. In this case, it can be worth explicitly pinning those too - you can easily pin all dependencies in a project automatically.

Listing packages from PyPI

Use the package name, pinned with an optional (but very strongly recommended) version number, for example:


Listing packages from version control systems or as archives

You can use the URL of a tarballed or zipped archive of the package, typically provided by a version control system.


More recent versions of pip tools as used in the Divio base projects require you to use URLS that provide the egg fragment (as shown in the examples below), and will raise an error if they encounter URLs lacking it. Older versions would allow you to omit the fragment.

Examples from GitHub

Master branch, as tarball:

or as a zipped archive:

Specify a different branch:

However, we very strongly recommend specifying either a tag:

or a commit:


Our pip set-up does not support VCS protocols - you cannot use for example URLs starting git+ or hg+, such as

However, as long as the version control system host offers full package downloads, you can use the tarball or zip archive URL for that to install from the VCS, as in the examples above.

Process the list

The requirements file is processed when the project is build. This is taken care of in Cloud deployments by the Dockerfile, and locally by running a build command:

docker-compose build web

Make sure that you don’t also have a requirements.txt of pinned dependencies, otherwise you will simply be re-installing the old list.