Dependency Management

Requirements

FlexMeasures is built on the shoulder of giants, namely other open source libraries. Look into the pyproject.toml file to see what is required to run FlexMeasures or to test it, or to build this documentation.

The pyproject.toml file specifies our general demands, and in the uv.lock file, we keep a set of pinned dependency versions, so we can all work on the same background (crucial to compare behavior of installations to each other).

We use the excellent uv tool to manage our dependencies. First, install uv, then pin it to the version this project requires:

$ uv self update 0.12.7

We enforce this exact version through [tool.uv].required-version in pyproject.toml, so that lockfile output is reproducible between contributors and CI. uv refuses to run at all on a version mismatch, so you will notice right away.

Note

uv self update only works if you installed uv with its standalone installer. If you installed it with pip or brew, pin it there instead (e.g. pip install uv==0.12.7).

Now install the dependencies:

$ uv sync --group dev --group test

To upgrade the dependencies to the latest compatible versions, we can run:

$ uv lock --upgrade

Upgrading uv itself is a deliberate step, which we take in the periodic chore: upgrade all dependencies PR. Because required-version gates every uv invocation, and not just uv lock, all the places where we pin uv have to move together, in one reviewed change:

  • [tool.uv].required-version in pyproject.toml

  • the version input of astral-sh/setup-uv in .github/workflows/lint-and-test.yml, .github/workflows/docker-build.yml, .github/workflows/docker-qa.yml, .github/workflows/pypi-publish.yml and .github/actions/setup-test-env/action.yml

  • ARG UV_VERSION in the Dockerfile (which selects the ghcr.io/astral-sh/uv base image)

  • the asdf commands under pre_create_environment in .readthedocs.yaml

Miss one, and that build fails rather than only producing a noisy lockfile.

Python versions

In addition, we support a range of Python versions (as you can see in the requires-python field in pyproject.toml).

Development generally happens on one specific Python version, namely the one specified in the python.version file.

Still, we’d also like to be able to test FlexMeasures across all these versions. We’ve added that capability to our CI pipeline (GitHub Actions), so you could clone it and make a PR, in order to run them.