refactor: Convert to use uv

.devcontainer/devcontainer.json

@@ -7,13 +7,20 @@
     },
     "remoteEnv": {
         // Allow X11 apps to run inside the container
-        "DISPLAY": "${localEnv:DISPLAY}"
+        "DISPLAY": "${localEnv:DISPLAY}",
+        // We put venv on a different volume to cache so have to copy
+        "UV_LINK_MODE": "copy",
+        // Do the equivalent of "activate" the venv so we don't have to "uv run" everything
+        "PATH": "/workspaces/${localWorkspaceFolderBasename}/.venv/bin:${containerEnv:PATH}"
     },
     "customizations": {
         "vscode": {
             // Set *default* container specific settings.json values on container create.
             "settings": {
-                "python.defaultInterpreterPath": "/venv/bin/python"
+                "python.defaultInterpreterPath": "/workspaces/${localWorkspaceFolderBasename}/.venv/bin/python",
+                "python.terminal.activateEnvInCurrentTerminal": false,
+                "python.terminal.activateEnvironment": false,
+                "remote.autoForwardPorts": false
             },
             // Add the IDs of extensions you want installed when the container is created.
             "extensions": [
@@ -27,20 +34,35 @@
             ]
         }
     },
-    "features": {
-        // add in eternal history and other bash features
-        "ghcr.io/diamondlightsource/devcontainer-features/bash-config:1": {}
-    },
-    // Create the config folder for the bash-config feature
-    "initializeCommand": "mkdir -p ${localEnv:HOME}/.config/bash-config",
+    // Create the config folder for the bash-config feature and uv cache
+    "initializeCommand": "mkdir -p ${localEnv:HOME}/.config/terminal-config ${localEnv:HOME}/.cache/uv",
     "runArgs": [
         // Allow the container to access the host X11 display and EPICS CA
         "--net=host",
         // Make sure SELinux does not disable with access to host filesystems like tmp
         "--security-opt=label=disable"
     ],
+    "mounts": [
+        // Mount in the user terminal config folder so it can be edited
+        {
+            "source": "${localEnv:HOME}/.config/terminal-config",
+            "target": "/user-terminal-config",
+            "type": "bind"
+        },
+        // Keep a persistent cross container cache for uv
+        {
+            "source": "${localEnv:HOME}/.cache/uv",
+            "target": "/root/.cache/uv",
+            "type": "bind"
+        },
+        // Use a volume mount for the uv venv so it is local to the container
+        {
+            "target": "/workspaces/${localWorkspaceFolderBasename}/.venv",
+            "type": "volume"
+        }
+    ],
     // Mount the parent as /workspaces so we can pip install peers as editable
     "workspaceMount": "source=${localWorkspaceFolder}/..,target=/workspaces,type=bind",
     // After the container is created, install the python project in editable form
-    "postCreateCommand": "pip install $([ -f dev-requirements.txt ] && echo '-c dev-requirements.txt') -e '.[dev]' && pre-commit install"
+    "postCreateCommand": "uv sync && uv run pre-commit install --install-hooks"
 }

.github/workflows/_dist.yml

@@ -12,10 +12,13 @@ jobs:
           # Need this to get version number from last tag
           fetch-depth: 0
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
       - name: Build sdist and wheel
         run: >
           export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct) &&
-          pipx run build
+          uvx --from build pyproject-build
 
       - name: Upload sdist and wheel as artifacts
         uses: actions/upload-artifact@v4
@@ -24,12 +27,10 @@ jobs:
           path: dist
 
       - name: Check for packaging errors
-        run: pipx run twine check --strict dist/*
+        run: uvx twine check --strict dist/*
 
       - name: Install produced wheel
-        uses: ./.github/actions/install_requirements
-        with:
-          pip-install: dist/*.whl
+        run: python -m pip install dist/*.whl
 
       - name: Test module --version works using the installed wheel
         # If more than one module in src/ replace with module name to test

.github/workflows/_docs.yml

@@ -20,11 +20,11 @@ jobs:
       - name: Install system packages
         run: sudo apt-get install graphviz
 
-      - name: Install python packages
-        uses: ./.github/actions/install_requirements
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
 
       - name: Build docs
-        run: tox -e docs
+        run: uv run --locked tox -e docs
 
       - name: Remove environment.pickle
         run: rm build/html/.doctrees/environment.pickle

.github/workflows/_test.yml

@@ -3,8 +3,8 @@ on:
     inputs:
       python-version:
         type: string
-        description: The version of python to install
-        required: true
+        description: The version of python to install, default is from .python-version file
+        default: ""
       runs-on:
         type: string
         description: The runner to run this job on
@@ -16,6 +16,7 @@ on:
 env:
   # https://github.com/pytest-dev/pytest/issues/2042
   PY_IGNORE_IMPORTMISMATCH: "1"
+  UV_PYTHON: ${{ inputs.python-version }}
 
 jobs:
   run:
@@ -28,30 +29,11 @@ jobs:
           # Need this to get version number from last tag
           fetch-depth: 0
 
-      - if: inputs.python-version == 'dev'
-        name: Install dev versions of python packages
-        uses: ./.github/actions/install_requirements
-
-      - if: inputs.python-version == 'dev'
-        name: Write the requirements as an artifact
-        run: pip freeze --exclude-editable > /tmp/dev-requirements.txt
-
-      - if: inputs.python-version == 'dev'
-        name: Upload dev-requirements.txt
-        uses: actions/upload-artifact@v4
-        with:
-          name: dev-requirements
-          path: /tmp/dev-requirements.txt
-
-      - if: inputs.python-version != 'dev'
-        name: Install latest versions of python packages
-        uses: ./.github/actions/install_requirements
-        with:
-          python-version: ${{ inputs.python-version }}
-          pip-install: ".[dev]"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
 
       - name: Run tests
-        run: tox -e tests
+        run: uv run --locked tox -e tests
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v5

.github/workflows/_tox.yml

@@ -15,8 +15,8 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Install python packages
-        uses: ./.github/actions/install_requirements
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
 
       - name: Run tox
-        run: tox -e ${{ inputs.tox }}
+        run: uv run --locked tox -e ${{ inputs.tox }}

.github/workflows/ci.yml

@@ -17,7 +17,6 @@ jobs:
   test:
     uses: ./.github/workflows/_test.yml
     with:
-      python-version: dev
       runs-on: ubuntu-latest
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/periodic.yml

@@ -10,4 +10,4 @@ jobs:
   linkcheck:
     uses: ./.github/workflows/_tox.yml
     with:
-      tox: docs build -- -b linkcheck
+      tox: docs -- -b linkcheck

.pre-commit-config.yaml

@@ -3,6 +3,7 @@ repos:
     rev: v5.0.0
     hooks:
       - id: check-added-large-files
+        args: ["--maxkb=1000"] # uv.lock is more than 500kB
       - id: check-yaml
       - id: check-merge-conflict
       - id: end-of-file-fixer
@@ -22,3 +23,10 @@ repos:
         entry: ruff format --force-exclude
         types: [python]
         require_serial: true
+
+      - id: uv-sync
+        name: update uv.lock and venv
+        pass_filenames: false
+        language: system
+        entry: uv sync
+        files: ^(uv\.lock|pyproject\.toml)$

.python-version

@@ -0,0 +1 @@
+3.11

Dockerfile

@@ -1,13 +1,8 @@
-# The devcontainer should use the developer target and run as root with podman
-# or docker with user namespaces.
-ARG PYTHON_VERSION=3.11
-FROM python:${PYTHON_VERSION} AS developer
+# The developer stage is used as a devcontainer including dev versions
+# of the build dependencies
+FROM ghcr.io/diamondlightsource/ubuntu-devcontainer:noble AS developer
 
 # Add any system dependencies for the developer/build environment here
 RUN apt-get update && apt-get install -y --no-install-recommends \
     graphviz \
-    && rm -rf /var/lib/apt/lists/*
-
-# Set up a virtual environment and put it in PATH
-RUN python -m venv /venv
-ENV PATH=/venv/bin:$PATH
+    && apt-get dist-clean

README.md

@@ -44,7 +44,7 @@ git init --initial-branch=main /path/to/my-project
 copier copy https://github.com/DiamondLightSource/python-copier-template.git $_
 ```
 
-You can also use it via `pipx run copier` if you have that installed.
+You can also use it via `uvx copier` if you have `uv` installed.
 
 <!-- README only content. Anything below this line won't be included in index.md -->
 

docs/explanations/decisions/0023-uv.md

@@ -0,0 +1,23 @@
+# 23. Adopt uv
+
+Date: 2025-09-22
+
+## Status
+
+Accepted
+
+## Context
+
+[`uv`](https://docs.astral.sh/uv/) appears to be gaining a critical mass of adoption, and adopting the project flow would bring some benefits:
+- Much faster venv creation times
+- A native lockfile implementation
+- A single base image that can install multiple pythons
+- Which would allow us to make a single devcontainer base with our feature built in, which would speed up the devcontainer creation time
+
+## Decision
+
+We will adopt this flow.
+
+## Consequences
+
+Docs will need to be updated, especially around lockfile support. Commands will need to be updated slightly for the new version of tox. Work on `renovate` will need to follow as `dependabot` does not support the uv lockfile.

docs/how-to/build-docs.md

@@ -20,10 +20,10 @@ $ firefox build/html/index.html
 
 ## Autobuild
 
-You can also run an autobuild process, which will watch your `docs` directory for changes and rebuild whenever it sees changes, reloading any browsers watching the pages:
+You can also run an autobuild process, which will watch your `docs` and `src` directories for changes and rebuild whenever it sees changes, reloading any browsers watching the pages:
 
 ```
-$ tox -e docs autobuild
+$ tox -e docs-autobuild
 ```
 
 You can view the pages at localhost:
@@ -32,8 +32,8 @@ You can view the pages at localhost:
 $ firefox http://localhost:8000
 ```
 
-If you are making changes to source code too, you can tell it to watch changes in this directory too:
+If you want to watch additional directories for changes you can pass these as argument to tox:
 
 ```
-$ tox -e docs autobuild -- --watch src
+$ tox -e docs-autobuild -- --watch tests
 ```

docs/how-to/lint.md

@@ -10,14 +10,14 @@ You can run the above checks on all files with this command:
 $ tox -e pre-commit
 ```
 
-Or you can install a pre-commit hook that will run each time you do a `git commit` on just the files that have changed:
+The devcontainer will also install a pre-commit hook that will run each time you do a `git commit` on just the files that have changed.
+
+If you want to commit with a failing pre-commit check then you have to:
 
 ```
-$ pre-commit install
+$ git commit --no-verify
 ```
 
-It is also possible to [automatically enable pre-commit on cloned repositories](https://pre-commit.com/#automatically-enabling-pre-commit-on-repositories). This will result in pre-commits being enabled on every repo your user clones from now on.
-
 ## Fixing issues
 
 The typical workflow is: