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 Cloud project has a requirements.in 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:

# <INSTALLED_ADDONS>...

# </INSTALLED_ADDONS>

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:

markdown=2.6.8

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.

Examples from GitHub

Master branch, as tarball:

https://github.com/account/repository/archive/master.tar.gz

or as a zipped archive:

https://github.com/account/repository/archive/master.zip

Specify a different branch:

https://github.com/account/repository/archive/develop.zip

However, we very strongly recommend specifying either a tag:

https://github.com/account/repository/archive/1.6.0.zip

or a commit:

https://github.com/account/repository/archive/2d8197e2ec4d01d714dc68810997aeef65e81bc1.zip

Note

Our pip set-up does not support VCS protocols - you cannot use for example URLs starting git+ or hg+, such as git+git@github.com:divio/django-cms.git.

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.