Managing Python dependencies#

There are countless ways to do it, but this document is nice for people not familiar with Python.

This assumes you have Python installed, with pip available.

Note

Of course, you can just always run a bare pip install (without versions), but dependencies can break from under you with upgrades.

We suggest to lock all dependencies' versions (recursively), so the same ones are always used.

As an example, let's use the typical list of dependencies mentioned throughout this site. Put these into the file requirements.in:

mkdocs
mkdocs-material
mkdocstrings-crystal
mkdocs-gen-files
mkdocs-literate-nav
mkdocs-section-index

Install the pip-compile tool:

$ pip install pip-tools

Note

This is needed only to manage the lock files; it won't be a permanent dependency.

And run it:

$ pip-compile -U requirements.in

(also run this whenever you want to upgrade the dependencies).

It creates the file requirements.txt, which is what you'll be using henceforth.

Example requirements.txt

#
# This file is autogenerated by pip-compile
# To update, run:
#
#    pip-compile requirements.in
#
cached-property==1.5.2
    # via mkdocstrings-crystal
click==7.1.2
    # via
    #   mkdocs
    #   nltk
future==0.18.2
    # via lunr
glob2==0.7
    # via mkdocs-literate-nav
jinja2==2.11.3
    # via
    #   mkdocs
    #   mkdocstrings
    #   mkdocstrings-crystal
joblib==1.0.1
    # via nltk
livereload==2.6.3
    # via mkdocs
lunr[languages]==0.5.8
    # via mkdocs
markdown==3.3.4
    # via
    #   mkdocs
    #   mkdocs-autorefs
    #   mkdocs-material
    #   mkdocstrings
    #   pymdown-extensions
markupsafe==1.1.1
    # via
    #   jinja2
    #   mkdocstrings
    #   mkdocstrings-crystal
mkdocs-autorefs==0.1.1
    # via mkdocstrings
mkdocs-gen-files==0.3.2
    # via -r requirements.in
mkdocs-literate-nav==0.3.1
    # via -r requirements.in
mkdocs-material-extensions==1.0.1
    # via mkdocs-material
mkdocs-material==7.0.3
    # via
    #   -r requirements.in
    #   mkdocs-material-extensions
mkdocs-section-index==0.2.3
    # via -r requirements.in
mkdocs==1.1.2
    # via
    #   -r requirements.in
    #   mkdocs-autorefs
    #   mkdocs-gen-files
    #   mkdocs-literate-nav
    #   mkdocs-material
    #   mkdocs-section-index
    #   mkdocstrings
mkdocstrings-crystal==0.3.1
    # via -r requirements.in
mkdocstrings==0.15.0
    # via mkdocstrings-crystal
nltk==3.5
    # via lunr
pygments==2.8.0
    # via mkdocs-material
pymdown-extensions==8.1.1
    # via
    #   mkdocs-material
    #   mkdocstrings
pytkdocs==0.11.0
    # via mkdocstrings
pyyaml==5.4.1
    # via mkdocs
regex==2020.11.13
    # via nltk
six==1.15.0
    # via
    #   livereload
    #   lunr
tornado==6.1
    # via
    #   livereload
    #   mkdocs
tqdm==4.58.0
    # via nltk

Now anyone (including automation) can install the exact same dependencies, and you can be sure the site will build as intended:

$ pip install -r requirements.txt

Tip

If you'll be maintaining several projects with different dependencies, you might want to install packages in a virtualenv (effectively localized just to this project's folder).

Important

Both requirements.in and requirements.txt should be checked into source control.

Depending on the layout of project, you have many options where to store those files:

at the root directory (more pragmatic);
as docs/requirements.txt (because, after all, this is docs' requirements, but you'll get a side effect that this file will become part of the built site);
any other location you come up with -- just use pip install -r any_other_location/requirements.txt.