ISSUE opendatahub-io#3032: chore(uv): pin uv version to fix CI check-generated-code failure (opendatahub-io#3034)

jiridanek · web-flow · commit 137aa9b98109 · 2026-02-27T19:34:33.000+01:00
# Context The check-generated-code CI job is failing on main and all PRs because astral-sh/setup-uv@v7 installs version: "latest" (currently uv 0.10.6), which produces different pylock.toml output than the committed files. The root cause is astral-sh/uv#18081 (released in uv 0.10.5, 2026-02-23) which added wheel filtering to pylock.toml even in --universal mode. See opendatahub-io#3032. Fix: pin uv version in uv.toml using required-version, remove version: "latest" from all workflows so setup-uv auto-detects the pin, and regenerate pylocks. # Changes 1. Create uv.toml at repo root required-version = "==0.10.6" setup-uv@v7 auto-detects this and installs the pinned version. Locally, uv errors if the running version doesn't match. 2. Update .github/workflows/code-quality.yaml Two setup-uv blocks (lines 17-24 and 46-53): - Remove version: "latest" line - Rename step from "Install the latest version of uv" to "Install uv" 3. Update .github/workflows/docs.yaml One setup-uv block (lines 21-28): - Remove version: "latest" line - Rename step 4. Update .github/workflows/security.yaml One setup-uv block (lines 19-26): - Remove version: "latest" line - Rename step 5. Update .github/workflows/build-notebooks-TEMPLATE.yaml One setup-uv block (lines 304-311): - Remove version: "latest" line - Rename step 6. Update ci/generate_code.sh Line 4 has a fallback pip install "uv==0.9.6" — update to "uv==0.10.6" to match the pinned version. 7. Regenerate pylocks bash ci/generate_code.sh This regenerates the 6 affected pylock.toml files with uv 0.10.6 filtering. # Files modified - uv.toml (new) - .github/workflows/code-quality.yaml - .github/workflows/docs.yaml - .github/workflows/security.yaml - .github/workflows/build-notebooks-TEMPLATE.yaml - ci/generate_code.sh - 6 pylock.*.toml files (regenerated) # Verification # Check that uv reads the required-version and doesn't error uv version # Regenerate and verify no diff bash ci/generate_code.sh git diff --stat # should show no changes after regeneration * ISSUE opendatahub-io#3032: chore(uv): create a ./uv wrapper to run the correct version of uv 1. Pre-flight check (lines 93-100): Added explicit validation that $UV wrapper exists and is executable before the existing command -v uv check. This prevents a misleading version error if the wrapper is missing. 2. Constraints flag (lines 291-316): Changed constraints_flag from a plain string to a bash array (local -a constraints_flag=()), and expanded it as "${constraints_flag[@]}" in the pip compile invocation. This avoids word-splitting on paths containing spaces.
diff --git a/.github/workflows/build-notebooks-TEMPLATE.yaml b/.github/workflows/build-notebooks-TEMPLATE.yaml
@@ -319,10 +319,10 @@ jobs:
       # region Pytest image tests
 
       # https://github.com/astral-sh/setup-uv
-      - name: Install the latest version of uv
+      - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
-          version: "latest"
+          version-file: uv.toml
           python-version: "3.14"
           enable-cache: true
           cache-dependency-glob: "uv.lock"
diff --git a/.github/workflows/code-quality.yaml b/.github/workflows/code-quality.yaml
@@ -15,10 +15,10 @@ jobs:
       - uses: actions/checkout@v6
 
       # https://github.com/astral-sh/setup-uv
-      - name: Install the latest version of uv
+      - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
-          version: "latest"
+          version-file: uv.toml
           python-version: "3.14"
           enable-cache: true
           cache-dependency-glob: "uv.lock"
@@ -44,10 +44,10 @@ jobs:
       - uses: actions/checkout@v6
 
       # https://github.com/astral-sh/setup-uv
-      - name: Install the latest version of uv
+      - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
-          version: "latest"
+          version-file: uv.toml
           python-version: "3.14"
           enable-cache: true
           cache-dependency-glob: "uv.lock"
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -19,10 +19,10 @@ jobs:
       - uses: actions/checkout@v6
 
       # https://github.com/astral-sh/setup-uv
-      - name: Install the latest version of uv
+      - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
-          version: "latest"
+          version-file: uv.toml
           python-version: "3.14"
           enable-cache: true
           cache-dependency-glob: "uv.lock"
diff --git a/.github/workflows/piplock-renewal.yaml b/.github/workflows/piplock-renewal.yaml
@@ -75,7 +75,9 @@ jobs:
           python-version: '3.12'
 
       - name: Install uv
-        run: pip install "uv==0.9.27"
+        uses: astral-sh/setup-uv@v7
+        with:
+          version-file: uv.toml
 
       - name: Run make refresh-lock-files
         run: |
diff --git a/.github/workflows/security.yaml b/.github/workflows/security.yaml
@@ -16,18 +16,18 @@ jobs:
       security-events: write
     steps:
 
+      - name: Checkout code
+        uses: actions/checkout@v6
+
       # https://github.com/astral-sh/setup-uv
-      - name: Install the latest version of uv
+      - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
-          version: "latest"
+          version-file: uv.toml
           activate-environment: false
           ignore-empty-workdir: true
           enable-cache: false
 
-      - name: Checkout code
-        uses: actions/checkout@v6
-
       # Trivy does not support pylock.toml https://github.com/aquasecurity/trivy/discussions/9408
       - run: find . -name pyproject.toml -execdir uv lock \;
 
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -2,15 +2,21 @@
 # https://github.com/pre-commit/pre-commit-hooks?tab=readme-ov-file#hooks-available
 repos:
   # https://docs.astral.sh/uv/guides/integration/pre-commit/
-  - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.9.29
+  # Using a local hook instead of uv-pre-commit so it goes through ./uv,
+  # which handles version mismatches without requiring the exact system uv.
+  - repo: local
     hooks:
       - id: uv-lock
+        name: uv-lock
+        entry: ./uv lock --locked
+        language: system
+        files: '(^uv\.lock$|^pyproject\.toml$|^uv\.toml$)'
+        pass_filenames: false
   # https://github.com/astral-sh/ruff-pre-commit
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.0
+    rev: v0.15.4
     hooks:
-      - id: ruff
+      - id: ruff-check
         types_or: [python, pyi]
         args: [--fix]
         files: 'ci/.*|tests/.*'
@@ -25,7 +31,7 @@ repos:
       - id: pyright
         name: Run Pyright on all files
         # entry: /bin/bash -c 'find. -name "*.py" | xargs pyright --pythonversion 3.12'
-        entry: uv run pyright --pythonversion 3.14
+        entry: ./uv run pyright --pythonversion 3.14
         pass_filenames: true
         types_or: [python, pyi]
         language: system
diff --git a/README.md b/README.md
@@ -62,17 +62,49 @@ Note: To ensure the GitHub Action runs successfully, users must add a `GH_ACCESS
 
 #### Prepare Python + uv + pytest env
 
+This project pins its uv version in `uv.toml` (`required-version`).
+Use the `./uv` wrapper script at the repo root — it reads the pinned
+version and runs it via `uvx`, so your system uv version doesn't matter:
+
 ```shell
 # Linux
 sudo dnf install python3.14
 pip install --user uv
-# MacOS
+# macOS
 brew install python@3.14 uv
 
-uv venv --python $(which python3.14)
-uv sync --locked
+./uv venv --python $(which python3.14)
+./uv sync --locked
 ```
 
+<details>
+<summary>Alternatives to <code>./uv</code></summary>
+
+The `./uv` wrapper is the recommended way, but you can also
+(replace `0.10.6` below with the version from `uv.toml`):
+
+- **Use `uvx` directly** with an explicit version:
+  ```shell
+  uvx uv@0.10.6 sync --locked
+  ```
+- **Use `uv tool run`** (equivalent, longer form):
+  ```shell
+  uv tool run uv@0.10.6 sync --locked
+  ```
+- **Install the exact version** so `uv` works directly:
+  ```shell
+  # Standalone installer (any OS)
+  curl -LsSf https://astral.sh/uv/0.10.6/install.sh | sh
+  # Or with pip
+  pip install uv==0.10.6
+  ```
+
+If your system uv matches the pinned version, you can use `uv` directly —
+`required-version` in `uv.toml` will let it through. If it doesn't match,
+uv exits with a clear error telling you which version is required.
+
+</details>
+
 #### Running Python selftests in Pytest
 By completing configuration in previous section, you are able to run any tests that don't need to start a container using following command:
 
@@ -106,15 +138,15 @@ sudo dnf install podman
 systemctl --user start podman.service
 systemctl --user status podman.service
 systemctl --user status podman.socket
-DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock uv run pytest tests/containers -m 'not openshift and not cuda and not rocm' --image quay.io/opendatahub/workbench-images@sha256:e98d19df346e7abb1fa3053f6d41f0d1fa9bab39e49b4cb90b510ca33452c2e4
+DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock ./uv run pytest tests/containers -m 'not openshift and not cuda and not rocm' --image quay.io/opendatahub/workbench-images@sha256:e98d19df346e7abb1fa3053f6d41f0d1fa9bab39e49b4cb90b510ca33452c2e4
 
 # Mac OS
 brew install podman
 podman machine init
 podman machine set --rootful=false
 sudo podman-mac-helper install
 podman machine start
-uv run pytest tests/containers -m 'not openshift' --image quay.io/opendatahub/workbench-images@sha256:e98d19df346e7abb1fa3053f6d41f0d1fa9bab39e49b4cb90b510ca33452c2e4
+./uv run pytest tests/containers -m 'not openshift' --image quay.io/opendatahub/workbench-images@sha256:e98d19df346e7abb1fa3053f6d41f0d1fa9bab39e49b4cb90b510ca33452c2e4
 ```
 
 When using lima on macOS, it might be useful to give yourself access to rootful podman socket
diff --git a/ci/generate_code.sh b/ci/generate_code.sh
@@ -1,8 +1,11 @@
 #!/usr/bin/env bash
 set -Eeuxo pipefail
 
-uv --version || pip install "uv==0.9.6"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 
-uv run scripts/dockerfile_fragments.py
-uv run manifests/tools/generate_kustomization.py
+uv --version || pip install "uv==0.10.6"
+
+"${REPO_ROOT}/uv" run scripts/dockerfile_fragments.py
+"${REPO_ROOT}/uv" run manifests/tools/generate_kustomization.py
 bash scripts/pylocks_generator.sh
diff --git a/scripts/pylocks_generator.sh b/scripts/pylocks_generator.sh
@@ -52,6 +52,7 @@ MAIN_DIRS=("jupyter" "runtimes" "rstudio" "codeserver")
 # CVE constraints file - applied to all lock file generations
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT_DIR="$(dirname "$SCRIPT_DIR")"
+UV="${ROOT_DIR}/uv"
 CVE_CONSTRAINTS_FILE="$ROOT_DIR/dependencies/cve-constraints.txt"
 
 # ----------------------------
@@ -89,13 +90,18 @@ read_conf_value() {
 # ----------------------------
 # PRE-FLIGHT CHECK
 # ----------------------------
+if [[ ! -x "$UV" ]]; then
+  error "Expected uv wrapper at '$UV' but it is missing or not executable."
+  exit 1
+fi
+
 if ! command -v uv &>/dev/null; then
   error "uv command not found. Please install uv: https://github.com/astral-sh/uv"
   exit 1
 fi
 
 UV_MIN_VERSION="0.4.0"
-UV_VERSION=$(uv --version 2>/dev/null | awk '{print $2}' || echo "0.0.0")
+UV_VERSION=$("$UV" --version 2>/dev/null | awk '{print $2}' || echo "0.0.0")
 
 version_ge() {
   [ "$(printf '%s\n' "$2" "$1" | sort -V | head -n1)" = "$2" ]
@@ -273,7 +279,9 @@ for TARGET_DIR in "${TARGET_DIRS[@]}"; do
       echo "➡️ Generating $(uppercase "$flavor") lock file..."
     fi
 
-    # The behavior has changed in uv 0.9.17 (https://github.com/astral-sh/uv/pull/16956)
+    # Tag filtering was added in uv 0.9.16 (https://github.com/astral-sh/uv/pull/16956)
+    # but bypassed in --universal mode. uv 0.10.5 (https://github.com/astral-sh/uv/pull/18081)
+    # now filters wheels by requires-python and marker disjointness even in --universal mode.
     # Documentation at https://docs.astral.sh/uv/reference/cli/#uv-pip-compile--python-platform says that
     #  `--python-platform linux` is alias for `x86_64-unknown-linux-gnu`; we cannot use this to get a multiarch pylock
     # Let's use --universal temporarily, and in the future we can switch to using uv.lock
@@ -285,17 +293,17 @@ for TARGET_DIR in "${TARGET_DIRS[@]}"; do
     # Build constraints flag if CVE constraints file exists
     # Use relative path to avoid absolute paths in pylock.toml headers
     # (which would differ between CI and local environments)
-    local constraints_flag=""
+    local -a constraints_flag=()
     if [[ -f "$CVE_CONSTRAINTS_FILE" ]]; then
       local relative_constraints
       # Use Python for cross-platform relative path computation (realpath --relative-to is GNU-only)
       relative_constraints=$(python3 -c "import os; print(os.path.relpath('$CVE_CONSTRAINTS_FILE', '$PWD'))")
-      constraints_flag="--constraints=$relative_constraints"
+      constraints_flag=(--constraints "$relative_constraints")
     fi
 
     set +e
     # shellcheck disable=SC2086
-    uv pip compile pyproject.toml \
+    "$UV" pip compile pyproject.toml \
       --output-file "$output" \
       --format pylock.toml \
       --generate-hashes \
@@ -309,7 +317,7 @@ for TARGET_DIR in "${TARGET_DIRS[@]}"; do
       --no-emit-package odh-notebooks-meta-runtime-datascience-deps \
       --no-emit-package odh-notebooks-meta-workbench-datascience-deps \
       $UPGRADE_FLAG \
-      $constraints_flag \
+      "${constraints_flag[@]}" \
       $index
     local status=$?
     set -e
diff --git a/uv b/uv
@@ -0,0 +1,40 @@
+#!/usr/bin/env -S bash --norc --noprofile
+# ./uv — run the project-pinned version of uv.
+#
+# Reads required-version from uv.toml and delegates via `uv tool run`.
+# This avoids version mismatch errors when your system uv (e.g. Homebrew)
+# differs from the version pinned for this project.
+#
+# Usage:
+#   ./uv sync
+#   ./uv run pytest
+#   ./uv pip compile ...
+#
+# The pinned version is cached by uvx after the first run.
+# Parsing uses bash =~ instead of forking sed to avoid a subprocess.
+#
+# Bash with built-in regex is ~3x faster than Python for this task (hyperfine,
+# 50 runs): bash+builtin 18.7ms, bash+sed 25.0ms, python 55.4ms.
+set -Eeuo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+while IFS= read -r line; do
+    if [[ "$line" =~ ^required-version\ *=\ *\"==([^\"]*)\" ]]; then
+        version="${BASH_REMATCH[1]}"
+        break
+    fi
+done < "${SCRIPT_DIR}/uv.toml"
+
+if [[ -z "${version:-}" ]]; then
+    echo "error: could not read required-version from ${SCRIPT_DIR}/uv.toml" >&2
+    exit 1
+fi
+
+# Fast path: use the system uv directly if it already matches the pinned version
+if current=$(uv --version 2>/dev/null) && [[ "$current" == "uv $version" || "$current" == "uv $version "* ]]; then
+    exec uv "$@"
+fi
+
+# Slow path: run the pinned version via uvx (downloaded and cached on first use)
+exec uv tool run "uv@${version}" "$@"
diff --git a/uv.toml b/uv.toml
@@ -0,0 +1 @@
+required-version = "==0.10.6"
