Use a uv.lock file and uv sync to manage local/CI dependencies

samueljsb · samueljsb · commit 525fec97e57c · 2026-04-02T19:29:33.000+01:00
Before this change, dependencies were listed as 'extras' and available
we used uv's pip wrapper to install dependencies and pinned the specific
versions we use in development and CI environments in pip requirement
text files.

This change switches to using uv. We now have a single lock file for all
dependency groups, and can *sync* our development environments, ensuring
unused dependencies are removed.

N.B. This change is as small as we can make it to switch to uv and
dependency groups. There are further improvements to the contributing
guide to bring this project into line with other Kraken projects that
might follow later.
diff --git a/.github/workflows/checks.yaml b/.github/workflows/checks.yaml
@@ -22,7 +22,7 @@ jobs:
           cache: 'pip'
           cache-dependency-path: |
             pyproject.toml
-            requirements/*.txt
+            uv.lock
             tox.ini
 
       - name: Make a virtualenv
@@ -31,7 +31,7 @@ jobs:
       - name: Install requirements
         run: |
           source .venv/bin/activate
-          make install
+          python -m pip install --group tox
 
       - name: Run linters
         run: |
diff --git a/.github/workflows/release-to-pypi.yaml b/.github/workflows/release-to-pypi.yaml
@@ -40,7 +40,7 @@ jobs:
             tox.ini
 
       - name: Install requirements
-        run: pip install --requirement requirements/release.txt
+        run: python -m pip install --group release
 
       - name: Verify version
         run: ./scripts/verify-version-tag.py
diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml
@@ -59,8 +59,7 @@ jobs:
       - name: Install requirements
         run: |
           source .venv/bin/activate
-          pip install --requirement requirements/prerequisites.txt
-          uv pip install --requirement requirements/tox.txt
+          python -m pip install --group tox
 
       - name: Run the tests
         run: |
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,6 +2,16 @@
 
 ## Local development
 
+The following tools must be available on your system
+to set up a development environment:
+
+- `make`
+- [Python]
+- [uv]
+
+[Python]: https://www.python.org/downloads/
+[uv]: https://docs.astral.sh/uv/
+
 ### Creating a virtual environment
 
 Ensure one of the supported Pythons (see README) is installed and used by the `python` executable:
@@ -14,13 +24,10 @@ Then create and activate a virtual environment. If you don't have any other way
 environments this can be done by running:
 
 ```sh
-python3 -m venv .venv
+make install
 source .venv/bin/activate
 ```
 
-You could also use [virtualenvwrapper], [direnv] or any similar tool to help manage your virtual
-environments.
-
 ### Install PostgreSQL
 
 Ensure that a supported version of PostgreSQL (see README) is installed and running on your local machine.
@@ -67,10 +74,8 @@ Package dependencies are declared in `pyproject.toml`.
 - _development_ dependencies in the `dev` array in the `[project.optional-dependencies]` section.
 
 For local development, the dependencies declared in `pyproject.toml` are pinned to specific
-versions using the `requirements/development.txt` lock file.
-You should not manually edit the `requirements/development.txt` lock file.
-
-Prerequisites for installing those dependencies are tracked in the `requirements/prerequisites.txt`.
+versions using the `uv.lock` lock file.
+You should not manually edit the `uv.lock` lock file.
 
 
 #### Adding a new dependency
@@ -84,14 +89,14 @@ make install
 
 This will:
 
-1. Build a new version of the `requirements/development.txt` lock file containing the newly added
+1. Build a new version of the `uv.lock` lock file containing the newly added
    package.
-2. Sync your installed packages with those pinned in `requirements/development.txt`.
+2. Sync your installed packages with those pinned in `uv.lock`.
 
 This will not change the pinned versions of any packages already in any requirements file unless
 needed by the new packages, even if there are updated versions of those packages available.
 
-Remember to commit your changed `requirements/development.txt` files alongside the changed
+Remember to commit your changed `uv.lock` files alongside the changed
 `pyproject.toml`.
 
 #### Removing a dependency
@@ -107,7 +112,7 @@ To update the pinned versions of all packages run:
 make update
 ```
 
-This will update the pinned versions of every package in the `requirements/development.txt` lock
+This will update the pinned versions of every package in the `uv.lock` lock
 file to the latest version which is compatible with the constraints in `pyproject.toml`.
 
 You can then run:
@@ -116,14 +121,14 @@ You can then run:
 make install
 ```
 
-to sync your installed packages with the updated versions pinned in `requirements/development.txt`.
+to sync your installed packages with the updated versions pinned in `uv.lock`.
 
 #### Updating individual Python packages
 
 Upgrade a single development dependency with:
 
 ```sh
-pip-compile -P $PACKAGE==$VERSION pyproject.toml --resolver=backtracking --extra=dev --output-file=requirements/development.txt
+uv lock -P $PACKAGE==$VERSION --resolver=backtracking
 ```
 
 You can then run:
@@ -132,6 +137,6 @@ You can then run:
 make install
 ```
 
-to sync your installed packages with the updated versions pinned in `requirements/development.txt`.
+to sync your installed packages with the updated versions pinned in `uv.lock`.
 
 [tox]: https://tox.wiki
diff --git a/makefile b/makefile
@@ -27,44 +27,21 @@ lint:
 
 .PHONY:update
 update:
-	uv pip compile pyproject.toml \
-		--quiet --upgrade --resolver=backtracking --strip-extras \
-		--group=dev \
-		--output-file=requirements/development.txt
-	uv pip compile pyproject.toml \
-		--quiet --upgrade --resolver=backtracking --strip-extras \
-		--group=pytest-in-tox \
-		--output-file=requirements/pytest-in-tox.txt \
-		--unsafe-package django
-	uv pip compile pyproject.toml \
-		--quiet --upgrade --resolver=backtracking --strip-extras \
-		--group=release \
-		--output-file=requirements/release.txt
-	uv pip compile pyproject.toml \
-		--quiet --upgrade --resolver=backtracking --strip-extras \
-		--group=tox \
-		--output-file=requirements/tox.txt
+	uv lock --upgrade --resolver=backtracking
 
 
 # Implementation details
 # ======================
 
-# Pip install all required Python packages
+# Install all required Python packages
 .PHONY:install_python_packages
-install_python_packages: install_prerequisites requirements/development.txt
-	uv pip sync requirements/development.txt
-
-.PHONY:install_prerequisites
-install_prerequisites: requirements/prerequisites.txt
-	pip install --quiet --requirement requirements/prerequisites.txt
+install_python_packages:
+	uv sync --group dev
 
 .PHONY:install_pre_commit
 install_pre_commit:
 	pre-commit install
 
-# Add new dependencies to requirements/development.txt whenever pyproject.toml changes
-requirements/development.txt: pyproject.toml
-	uv pip compile pyproject.toml \
-		--quiet --resolver=backtracking --strip-extras \
-		--extra=dev \
-		--output-file=requirements/development.txt
+# Add new dependencies to uv.lock whenever pyproject.toml changes
+uv.lock: pyproject.toml
+	uv lock --upgrade --resolver=backtracking
diff --git a/requirements/prerequisites.txt b/requirements/prerequisites.txt
diff --git a/tox.ini b/tox.ini
@@ -12,8 +12,8 @@ wheel_build_env = .pkg
 
 pass_env =
     DATABASE_URL
+dependency_groups = pytest-in-tox
 deps =
-    -r requirements/pytest-in-tox.txt
     django42: django>=4.2,<5.0
     django50: django>=5.0,<5.1
     psycopg2: psycopg2-binary
diff --git a/uv.lock b/uv.lock
