How to install Python dependencies in a project¶
It’s beyond the scope of this documentation to discuss all the ways in which Python dependencies can be installed in Divio projects. However, the options described here are sufficient to cover most needs.
If you are using Aldryn Django, refer to the section Python package installation in Aldryn Django projects below.
pip install and
The simplest option is to list Python requirements in a
requirements.txt file, and include the command:
RUN pip install -r requirements.txt
Dockerfile. See How to configure an existing Django application for deployment on Divio for an example.
However this is only adequate as a quick expedient in the early stages of development and is not recommended beyond that, as it does not allow for complete pinning of all dependencies.
Pin all dependencies¶
Unpinned dependencies are the number one cause of deployment failures. Nothing in the codebase may have changed, but a fresh build can unexpectedly pick up a newly-released version of a package.
All Python dependencies, including implicit sub-dependencies, should be pinned to particular versions.
If any dependency is unpinned (that is, a particular version is not specified in the project’s requirements)
will install the latest version it finds, even if a different version was previously installed. This can cause your
your project to fail with an deployment error or worse, a runtime error, the next time it is built - even if you
didn’t change anything in it yourself.
To pin all dependencies, your project’s requirements should be compiled to a complete list of explicitly specified package versions. This list should then be committed in the project repository, and not be changed until you need to update dependencies.
Once you are able to build and run your application successfully, you know have a working set of Python dependencies
pip freeze to write them in a new file:
docker-compose run web pip freeze > compiled_requirements.txt
And then ensure that the pip command in the Dockerfile uses that list:
RUN pip install -r compiled_requirements.txt
You can use the tool of your choice. In each case, the tool itself needs to be available in the Docker build
environment. You can expect to find
pip to be installed by default, but other tools will generally need to be
installed manually in the
An example using
RUN pip install pip-tools==5.5.0 RUN pip-compile requirements.in RUN pip-sync requirements.txt
requirements.txt, then installs the components listed
Once you have a working set of dependencies, remove the
pip-compile instruction so that the dependencies are pinned
and frozen in
Python package installation in Aldryn Django projects¶
To install Python dependencies an Aldryn project, list them in the
requirements.in file. They need to be outside
# <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.
This list is processed by the
pip commands in the
Dockerfile when the image is built.
Pinning dependencies in an Aldryn project¶
First, you need to have a working local set-up. Then run:
docker-compose run --rm web pip-reqs compile
This will create a
requirements.txt file in the project, containing a list of all the packages in the
environment, along with their versions.
When your project is built using the new
requirements.txt instead of
you’ll have a guarantee that no unexpected changes will be permitted to find their way in to the
In order to have your project built using
requirements.txt instead of
need to remove the
pip-reqs compile instruction from your project’s
First, remove the Divio-specific comment tags from the
# <PYTHON> ... # </PYTHON>
otherwise the Control Panel will simply overwrite your changes.
Then remove the
pip-reqs compile instruction, so that
requirements.txt will not be amended at the next build.
The next time you need to create a fresh
docker-compose run web pip-reqs compile
Specifying packages via a URL¶
Please use a commit hash when specifying packages via a URL of a tarballed or zipped archive.
Branch names or tags are not supported as part of the archive name and will break. Please use the commit hash as described above.
Recent versions of
pip-tools require the use of URLS that provide both the
egg fragment and the version
fragment (for example,
egg=package-name==1.0), and will raise a
Bad Request for url error if they encounter
URLs lacking it. Older versions would allow you to omit the fragment.
pip-tools does note support VCS protocols
- for example, you cannot use URLs starting with
hg+, such as