CI: `check-generated-code` failing on main due to uv 0.10.5+ pylock.toml filtering change

[jiridanek]

Summary

The check-generated-code CI job has been failing on main (and all PRs) since ~Feb 23 2026. The job regenerates lock files via bash ci/generate_code.sh and then checks for uncommitted changes. Six pylock.toml files are regenerated differently by CI than what is committed, causing the check to fail.

This is not caused by any PR — it is a repo-wide issue triggered by a behavior change in uv 0.10.5 (released 2026-02-23).

Failing files

M codeserver/ubi9-python-3.12/uv.lock.d/pylock.cpu.toml
M jupyter/datascience/ubi9-python-3.12/uv.lock.d/pylock.cpu.toml
M jupyter/rocm/tensorflow/ubi9-python-3.12/pylock.toml
M jupyter/trustyai/ubi9-python-3.12/uv.lock.d/pylock.cpu.toml
M runtimes/datascience/ubi9-python-3.12/uv.lock.d/pylock.cpu.toml
M runtimes/rocm-tensorflow/ubi9-python-3.12/pylock.toml

Example CI run on main: https://github.com/opendatahub-io/notebooks/actions/runs/22481514656/job/65121631498

Example CI run on a PR: https://github.com/opendatahub-io/notebooks/actions/runs/22482916427/job/65125645371

Root cause

Our CI workflow (.github/workflows/code-quality.yaml) installs uv with version: "latest" via astral-sh/setup-uv@v7. The pylocks_generator.sh script runs uv pip compile --universal --format pylock.toml, and a recent uv release changed what --universal includes in pylock.toml output.

What changed in uv

astral-sh/uv#18081 — "Filter pylock.toml wheels by tags and requires-python" (merged 2026-02-18, released in uv 0.10.5 on 2026-02-23).

This PR unified the wheel filtering logic between uv.lock and pylock.toml. Previously, pylock.toml in --universal mode included all resolved wheels with no filtering. After this PR, even in --universal mode, uv now:

1. Filters by requires-python — removes wheels for Python versions outside the project's requirement (e.g., cp39, cp310, cp311 wheels when requires-python >= "3.12").
2. Filters by platform marker disjointness — removes wheels for platforms provably unreachable based on a dependency's marker expression (e.g., macOS/Windows wheels for Linux-only deps, s390x wheels for packages with architecture-restricting markers).

Full timeline of --universal + pylock.toml behavior

uv version	Date	PR	Impact on --universal pylock.toml
< 0.9.16			No filtering at all — ALL wheels dumped into output
0.9.16	2025-12-06	#16956	Added tag filtering, but explicitly skipped in --universal mode (tags.is_none_or(...) passes all wheels through). Only filters when NOT using --universal.
0.9.22	2026-01-06	#17317	Extended architecture filtering (ppc64le, s390x, riscv64, etc.) but only for uv.lock, not pylock.toml.
0.10.5	2026-02-23	#18081	Breaking change for us. Extracted is_wheel_unreachable() from uv.lock code path and reused it in pylock.toml. Now filters even with --universal based on requires-python and marker disjointness.

What the diff looks like

The regenerated pylocks remove wheels for:

• macOS and Windows platforms (e.g., cp312-cp312-macosx_*, cp312-cp312-win_*)
• Older Python versions not matching requires-python (cp39, cp310, cp311)
• s390x architecture for some Red Hat-index packages (greenlet, grpcio, msgpack, wrapt) where markers make it unreachable

This is arguably the correct behavior — these wheels were never needed in our Linux-only container builds.

Why it doesn't fail locally

Developers with uv < 0.10.5 (e.g., uv 0.10.4 from Homebrew) generate pylocks that include all wheels. CI with uv 0.10.5+ generates pylocks with the filtered set, producing a diff.

Note about pylocks_generator.sh comment

Line 276-278 of scripts/pylocks_generator.sh says:

# The behavior has changed in uv 0.9.17 (https://github.com/astral-sh/uv/pull/16956)

Minor correction: PR #16956 was released in uv 0.9.16 (not 0.9.17), and it did NOT change --universal behavior for pylock.toml — the tag filtering is explicitly bypassed in universal mode. The actual change affecting our --universal output is PR #18081 in uv 0.10.5.

Suggested fix

Regenerate the pylocks with uv >= 0.10.5:

# Update uv first
# e.g.: brew upgrade uv, or: pip install -U uv, or: curl -LsSf https://astral.sh/uv/install.sh | sh

# Then regenerate
bash ci/generate_code.sh

# Commit the updated pylocks
git add -A '*.toml'
git commit -m "chore: regenerate pylock.toml files with uv 0.10.5+ filtering"

Alternatively (or additionally), pin the uv version in .github/workflows/code-quality.yaml to avoid future surprises from version: "latest":

- uses: astral-sh/setup-uv@v7
  with:
    version: "0.10.6"  # pin to avoid breaking on new releases

[jiridanek]

Proposed fix: pin uv version with required-version in uv.toml

The problem beyond CI

The issue description suggests two options: regenerate pylocks, or pin the uv version in CI. But regenerating alone doesn't prevent this from happening again — any future uv release could change resolution behavior and break CI again, since we use version: "latest" in all four workflow files.

The deeper problem is that CI and local developers can run different uv versions, producing different lock file output. We need a single source of truth for the uv version.

Recommended approach: required-version in uv.toml

uv has a native required-version setting (available since uv 0.5.14, astral-sh/uv#10248). Create a uv.toml at the repo root:

required-version = "==0.10.6"

This gives us two things:

1. CI auto-detection: astral-sh/setup-uv@v7 automatically reads required-version from uv.toml when no explicit version: input is provided (setup-uv docs: version resolution priority). We just remove version: "latest" from workflows and the action installs the pinned version. No version-file: config needed.

2. Local enforcement: When a developer runs any uv command with a mismatched version, uv itself exits with an error. No extra tooling required.

The auto-detection priority in setup-uv is:

1. Explicit version input → 2. version-file input → 3. required-version in uv.toml → 4. required-version in pyproject.toml [tool.uv] → 5. Fall back to latest

Important: the constraint must use the ==X.Y.Z format. Ranges like >=0.10.5 won't work for CI auto-detection — setup-uv only strips the == prefix (setup-uv source).

Alternatives considered and dismissed

.tool-versions (asdf/mise)

The asdf-uv plugin and mise support pinning uv in a .tool-versions file. setup-uv can read it via the version-file: input. However:

• Requires developers to install asdf or mise — an additional dependency this repo doesn't use
• Does not auto-detect in CI — you must explicitly set version-file: ".tool-versions" in every workflow
• No runtime validation: if someone bypasses the shim and runs a system-installed uv, there's no error
• Two maintenance burdens if combined with required-version

.uv-version file

There is no .uv-version file convention. astral-sh/setup-uv#215 requested this but it was resolved by implementing required-version auto-detection instead.

requires-uv in pyproject.toml (PEP standard)

astral-sh/uv#8605 requested a standardized requires-uv field. The outcome was the [tool.uv] required-version setting — a tool-specific namespace rather than a PEP standard. We could put it in pyproject.toml instead of uv.toml; either location works for both uv and setup-uv. A standalone uv.toml is arguably cleaner since it's a single-purpose file and immediately visible in the repo root.

uv.lock — does not help

uv.lock locks Python package dependency versions. It does not contain or enforce the version of uv itself.

Concrete changes needed

1. Create uv.toml at repo root with required-version = "==0.10.6"
2. Remove version: "latest" from all workflow files that use setup-uv (code-quality.yaml, build-notebooks-TEMPLATE.yaml, docs.yaml, security.yaml)
3. Regenerate pylocks with uv 0.10.6: bash ci/generate_code.sh
4. Commit the updated pylocks + uv.toml + workflow changes

Steps 1-2 prevent future breakage. Steps 3-4 fix the current failure.

[jiridanek]

@coderabbitai analyze

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash

# First, let's check the repository structure
echo "=== Repository root structure ==="
ls -la

echo -e "\n=== Checking for existing uv configuration files ==="
fd -t f "^uv\.toml$" .
fd -t f "^pyproject\.toml$" . --max-depth 2

echo -e "\n=== Looking for workflow files ==="
fd -t f "\.ya?ml$" .github/workflows/

echo -e "\n=== Checking current uv version setup in workflow files ==="
rg -n "astral-sh/setup-uv" .github/workflows/ -A 5 -B 2

Length of output: 7216

---

🏁 Script executed:

#!/bin/bash

# Check if pyproject.toml has any [tool.uv] configuration
echo "=== Checking pyproject.toml for [tool.uv] section ==="
cat pyproject.toml | rg -A 10 "^\[tool\.uv\]" || echo "No [tool.uv] section found"

echo -e "\n=== Checking pyproject.toml structure ==="
cat pyproject.toml | rg "^\[" | head -20

# Use GitHub CLI to fetch issue details
echo -e "\n=== Fetching GitHub issue `#3032` ==="
gh issue view 3032 --json title,body,labels,state,createdAt,author --repo opendatahub-io/notebooks

Length of output: 5928

---

@jiridanek Your analysis is excellent and the proposed solution is spot-on. I've verified the current state of the repository and the approach aligns perfectly with best practices. Here's my assessment:

✅ Confirmed: Current State

• No uv.toml exists currently
• pyproject.toml has [tool.uv] section but no required-version field
• Four workflow files using version: "latest":
  • code-quality.yaml (lines 21 and 50 - two jobs)
  • docs.yaml (line 25)
  • security.yaml (line 23)
  • build-notebooks-TEMPLATE.yaml (line 308)
• Issue #3032 confirms the CI failure is due to uv 0.10.5+ filtering changes in astral-sh/uv#18081

✅ Validated: Your Approach is Best Practice

Your uv.toml + required-version proposal is the canonical solution recommended by the uv team:

1. CI auto-detection works as described — setup-uv@v7 will automatically read required-version from uv.toml when no explicit version: input is provided (priority order documented)

2. Local enforcement is native — uv itself exits with an error on version mismatch, no additional tooling required

3. Single source of truth — eliminates version drift between CI and local development

4. Format constraint correctly identified — ==X.Y.Z is required for CI auto-detection (ranges won't work)

Your dismissal of alternatives is also correct:

• .tool-versions requires extra tooling and no CI auto-detection
• .uv-version convention doesn't exist (resolved by required-version feature)
• pyproject.toml [tool.uv] works but uv.toml is cleaner

📋 Implementation Checklist

Your concrete changes are accurate:

1. ✅ Create uv.toml at repo root:

   required-version = "==0.10.6"

2. ✅ Remove version: "latest" from 4 workflow files:

   • .github/workflows/code-quality.yaml (lines 21 and 50)
   • .github/workflows/docs.yaml (line 25)
   • .github/workflows/security.yaml (line 23)
   • .github/workflows/build-notebooks-TEMPLATE.yaml (line 308)

3. ✅ Regenerate pylocks: bash ci/generate_code.sh (with uv 0.10.6)

4. ✅ Commit all changes together

Additional Considerations

• No other workflow changes needed — the other workflows in .github/workflows/ don't use setup-uv, so they're unaffected
• Developer onboarding — consider adding a note to CONTRIBUTING.md or README.md about the uv version requirement (uv will enforce it, but documentation helps)
• Future updates — when bumping the uv version, update uv.toml and regenerate pylocks in the same PR

Your analysis is production-ready. This solution prevents the exact issue you encountered from recurring.

[jiridanek]

Local enforcement: When a developer runs any uv command with a mismatched version, uv itself exits with an error. No extra tooling required.

@coderabbitai this sounds like a poor developer experience

[coderabbitai]

🧩 Analysis chain

🌐 Web query:

uv required-version error message developer experience

💡 Result:

uv supports a [tool.uv] required-version = "<PEP 440 specifier>" setting (in pyproject.toml or uv.toml) to enforce that the running uv version matches your project’s expectation; if it doesn’t, uv exits with an error. [1]

What the error looks like (current DX)

A typical failure is explicit but blocking, e.g.:
error: Required uv version '>=0.5.0, <0.5.19' does not match the running version '0.5.25' (from an upstream feature request describing real workflows). [2]

Why developers report friction

In teams/CI/Docker, it’s common to pin an older uv in containers while developers have newer uv locally. With required-version set, developers with newer uv can’t run normal commands (like uv lock) unless they manually re-run via uv tool run to execute a compatible uv version. [2]

Common workaround / proposed improvement

• A community workaround is uv-required-version, a wrapper that detects required-version and then runs the matching uv via uv tool run "uv==<required-version>" ..., so developers don’t have to remember the extra steps. [3]
• The upstream request is for uv itself to automatically do this handoff (auto-install/run the matching uv) instead of erroring. [2]

Sources: [1] uv settings docs (required-version), [2] astral-sh/uv issue #11065 (DX + exact error example), [3] uv-required-version project description.

---

🌐 Web query:

uv installation upgrade switch versions how to

💡 Result:

Install uv

• macOS/Linux (standalone installer):

  curl -LsSf https://astral.sh/uv/install.sh | sh

• Windows (PowerShell, standalone installer):

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

• Install a specific uv version (example):

  curl -LsSf https://astral.sh/uv/0.10.0/install.sh | sh

  [1]

Upgrade uv

• If you installed via the standalone installer:

  uv self update

• If you installed via pip:

  pip install --upgrade uv

  [1]

---

Manage / switch Python versions with uv

See what Python versions are available/installed

uv python list
# or only installed:
uv python list --only-installed

[2]

Install a Python version

uv python install 3.12.3   # exact
uv python install 3.12     # latest patch for that minor line

[2]

“Switch” Python for a project (pin a default)

uv will read a .python-version file in your project (or parent dirs). Create/update it with:

uv python pin 3.12
# or global default:
uv python pin --global 3.12

[2]

Use a specific Python for a single command (no pin)

Most commands accept --python:

uv venv --python 3.12

[2]

Upgrade uv-managed Python patch versions

uv python upgrade 3.12   # upgrade that minor line to latest supported patch
uv python upgrade        # upgrade all uv-managed CPython versions

[2]

Note: Python versions available for download are bundled with each uv release—if you can’t see a newer Python patch available, upgrading uv may be required. [2]

Sources: Installation & upgrading uv [1]; Python version install/pin/upgrade behavior [2].

[1] https://docs.astral.sh/uv/getting-started/installation/
[2] https://docs.astral.sh/uv/concepts/python-versions/

---

@jiridanek You raise a valid concern. Let me clarify the tradeoffs:

The friction is real, but intentional

When required-version is set, uv exits with an error if the running version doesn't match, like: error: Required uv version '>=0.5.0, <0.5.19' does not match the running version '0.5.25'

This does create a hard stop for developers with mismatched versions. However, the alternative is what you're experiencing now: silent version drift where CI and local produce different lock files, causing mysterious failures.

It's a deliberate tradeoff

The strict enforcement is actually preventing worse DX:

• ❌ Without enforcement: Developer unknowingly regenerates pylocks with uv 0.10.7, commits them, CI (pinned to 0.10.6) fails mysteriously, wastes time debugging
• ✅ With enforcement: Developer gets immediate, clear error: "you need uv 0.10.6", fixes it once, never diverges again

Options to reduce friction

You have flexibility in how strict you want to be:

Option 1: Exact pin (strictest, clearest)

required-version = "==0.10.6"

• Guarantees byte-identical lock files
• Developer must run uv self update to switch versions (takes ~2 seconds)
• Best for teams prioritizing reproducibility

Option 2: Range (more flexible)

required-version = ">=0.10.6,<0.11"

• Allows patch version drift within 0.10.x
• Ranges work for local enforcement, but CI auto-detection in setup-uv still requires ==X.Y.Z format
• Would need to explicitly set version: "0.10.6" in workflows (loses auto-detection benefit)

Option 3: Community wrapper

The uv-required-version wrapper automatically detects required-version and runs the matching uv via uv tool run — developers never see the error, it just works. Adds one dependency but smoothest experience.

Option 4: No enforcement

Skip required-version entirely and manually coordinate versions. You'd rely on code review to catch lock file drift.

My recommendation

Start with Option 1 (exact pin). The "poor DX" of a version mismatch error is:

1. Rare — happens once per developer, once per version bump
2. Clear — error message tells you exactly what to do
3. Fast to fix — uv self update or curl -LsSf https://astral.sh/uv/0.10.6/install.sh | sh
4. Better than current state — prevents the confusing CI failures you're debugging now

The upstream uv team is considering auto-switching in astral-sh/uv#11065, which would eliminate this friction entirely. Until then, explicit enforcement is the least-bad option for version-sensitive lock files.

Does that address your concern, or would you prefer one of the more flexible approaches?

[jiridanek]

❯ uv self update
error: uv was installed through an external package manager and cannot update itself.

hint: You installed uv using Homebrew. To update uv, run `brew update && brew upgrade uv`

@coderabbitai we need the wrapper, I believe

[coderabbitai]

@jiridanek You're absolutely right. The uv-required-version wrapper automatically runs uv tool run "uv==<required-version>" <commands> when it detects a required-version setting, which solves the Homebrew friction.

However, there's a simpler built-in solution that doesn't require installing the wrapper:

Option A: Built-in uv tool run (no wrapper needed)

Developers can run any uv command through a specific version using uv's built-in tool functionality:

# Instead of:
uv lock

# Run with pinned version:
uv tool run uv@0.10.6 lock

This works even with Homebrew-installed uv because uv tool run downloads and runs the specified version in isolation. When version mismatch occurs, developers currently need to use uv tool run --with 'uv>=0.5.0,<0.5.19' uv lock to bypass the error.

You can document this in the README.md or CONTRIBUTING.md:

## Working with uv

This project requires uv 0.10.6 (specified in `uv.toml`). If your system has a different version installed:

```bash
# Run any uv command through the pinned version
uv tool run uv@0.10.6 lock
uv tool run uv@0.10.6 sync

## Option B: Install the wrapper

If typing `uv tool run uv@0.10.6` repeatedly feels cumbersome, the `uv-required-version` wrapper respects the `required-version` setting in your `pyproject.toml` / `uv.toml` file and automatically runs `uv tool run "uv==<required-version>" <commands>`.

```bash
# Install once
uv tool install uv-required-version

# Then just use it as a drop-in replacement for uv
uv-required-version lock
uv-required-version sync

The wrapper adds one more dependency to track, but makes the DX seamless.

My revised recommendation

Given the Homebrew constraint:

1. Keep uv.toml with required-version = "==0.10.6" — this ensures CI uses the correct version (auto-detected by setup-uv) and local validation still works
2. Document the uv tool run uv@0.10.6 workaround in CONTRIBUTING.md for developers who hit the version mismatch
3. Optionally mention the wrapper as a convenience tool for those who prefer it

This approach:

• ✅ Prevents CI drift (the original problem)
• ✅ Works for everyone regardless of install method (Homebrew, standalone, pipx)
• ✅ Doesn't force an additional tool dependency
• ✅ Provides a clear escape hatch for version mismatches

The key insight: uv tool run can automatically find and run a version of uv itself that matches requirements instead of exiting with an error, which is what the upstream team is considering implementing natively in astral-sh/uv#11065.

Would you prefer documenting the built-in uv tool run approach, or adding the wrapper as a recommended tool for contributors?

[jiridanek]

@coderabbitai this should not be external package, we can vendor it in our project

"""
uv-required-version
"""

import argparse
import logging
import pathlib
import shutil
import subprocess
import sys
from os import getenv
from typing import Sequence

from uv import find_uv_bin

logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.getLevelName(getenv("LOG_LEVEL", "WARNING").upper()))

if sys.version_info >= (3, 11):
    import tomllib
else:
    import tomli as tomllib  # pragma: no cover

logger = logging.getLogger(__name__)

UV_CONFIG_FILES = [
    "uv.toml",
    "pyproject.toml",
]


def find_config_file() -> pathlib.Path | None:
    """
    Find the first available uv config file by traversing the current directory and its parents.
    """
    config_file = None
    current_path = pathlib.Path.cwd().resolve()
    while current_path != current_path.parent:
        for config_name in UV_CONFIG_FILES:
            file_path = current_path / config_name
            if file_path.exists():
                return file_path
        current_path = current_path.parent
    return config_file


def find_uv_binary() -> pathlib.Path:
    """
    Find the uv binary.

    First, try to find the uv binary in the system PATH.
    If not found, use the uv.find_uv_bin function to locate it.
    """
    uv_binary = shutil.which("uv")
    if not uv_binary:
        uv_binary = find_uv_bin()
    return pathlib.Path(uv_binary)


def get_uv_version(config_file: pathlib.Path) -> str | None:
    """
    Get the UV version from the config file.
    If no version is found, it will return None.
    """
    config_file_content = config_file.read_text(encoding="utf-8")
    config_file_dict = tomllib.loads(config_file_content)
    if config_file.name == "uv.toml":
        version = config_file_dict.get("required-version")
    elif config_file.name == "pyproject.toml":
        version = config_file_dict.get("tool", {}).get("uv", {}).get("required-version")
    else:
        raise ValueError(f"Unsupported config file: {config_file.name}")
    if not version:
        return None
    else:
        version = str(version).strip()
        if version[0].isdigit():
            version = f"=={version}"
        return f"uv{version.strip()}"


def uv_required_version(
    args: Sequence[str], capture_output: bool = False
) -> subprocess.CompletedProcess:
    """
    Run the uv-required-version Workflow.

    1) Find the UV config file in the current directory or its parents.
    2) Get the UV version from the config file.
    3) Find the UV binary in the system PATH or using uv.find_uv_bin.
    4) Construct the CLI command to run UV with the specified version.
    5) Execute the command with the provided arguments.
    """
    config_file = find_config_file()
    logger.debug("<uv-required-version> Config File: %s", config_file)
    uv_version = get_uv_version(config_file=config_file) if config_file else None
    logger.debug("<uv-required-version> UV Version: %s", uv_version)
    uv_binary = find_uv_binary()
    logger.debug("<uv-required-version> UV Binary: %s", uv_binary)
    logger.debug("<uv-required-version> UV Args: %s", args)
    cli_args = list(args)
    if uv_version:
        cli_args = ["tool", "run", uv_version] + cli_args
    cli_args = [str(uv_binary)] + cli_args
    logger.debug("<uv-required-version> Managed CLI: %s", cli_args)
    print(f"\033[1;33muv-required-version: {uv_version}\033[0m", file=sys.stderr)
    result = subprocess.run(args=cli_args, check=False, capture_output=capture_output)
    return result


def cli(capture_output: bool = False) -> subprocess.CompletedProcess:
    """
    uv-required-version
    """
    parser = argparse.ArgumentParser(add_help=False)
    _, args = parser.parse_known_args()
    result = uv_required_version(args=args, capture_output=capture_output)
    sys.exit(result.returncode)
    return result  # noqa


if __name__ == "__main__":  # pragma: no cover
    cli()

MIT License

Copyright © 2025 Justin Flannery

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

https://pypi.org/project/uv-required-version

[jiridanek]

import pathlib
import types
from unittest.mock import MagicMock, patch

import pytest

import uv_required_version


def test_find_config_file_found(
    tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """
    Test that find_config_file returns the config file when it exists in the current directory.

    Scenario: File is found in current directory.
    """
    config = tmp_path / "uv.toml"
    config.write_text("required-version = '1.2.3'")
    monkeypatch.chdir(tmp_path)
    found = uv_required_version.find_config_file()
    assert found == config


def test_find_config_file_found_in_parent(
    tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """
    Test that find_config_file finds the config file in a parent directory.

    Scenario: File is found in parent directory.
    """
    parent = tmp_path
    child = tmp_path / "child"
    child.mkdir()
    config = parent / "pyproject.toml"
    config.write_text("[tool.uv]\nrequired-version = '==2.0.0'")
    monkeypatch.chdir(child)
    found = uv_required_version.find_config_file()
    assert found == config


def test_find_config_file_not_found(
    tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """
    Test that find_config_file returns None if no config file is found.

    Scenario: Config file is not found.
    """
    monkeypatch.chdir(tmp_path)
    assert uv_required_version.find_config_file() is None


def test_find_uv_binary_system_path(monkeypatch: pytest.MonkeyPatch) -> None:
    """
    Test that find_uv_binary returns the correct path when found in the system PATH.

    Scenario: Found via system PATH.
    """
    monkeypatch.setattr(
        uv_required_version.shutil, "which", lambda _: "/usr/local/bin/uv"
    )
    result = uv_required_version.find_uv_binary()
    assert str(result) == "/usr/local/bin/uv"


def test_find_uv_binary_fallback(monkeypatch: pytest.MonkeyPatch) -> None:
    """
    Test that find_uv_binary falls back to find_uv_bin if not found in PATH.

    Scenario: Fallback to find_uv_bin when not found in PATH.
    """
    monkeypatch.setattr(uv_required_version.shutil, "which", lambda _: None)
    monkeypatch.setattr(uv_required_version, "find_uv_bin", lambda: "/another/path/uv")
    result = uv_required_version.find_uv_binary()
    assert str(result) == "/another/path/uv"


@pytest.mark.parametrize(
    "filename,contents,expected",
    [
        ("uv.toml", "required-version = '==1.2.3'", "uv==1.2.3"),
        ("pyproject.toml", "[tool.uv]\nrequired-version = '==2.0.0'", "uv==2.0.0"),
        ("uv.toml", "", None),
        ("pyproject.toml", "[tool.uv]\n", None),
    ],
)
def test_get_uv_version(
    filename: str, contents: str, expected: str | None, tmp_path: pathlib.Path
) -> None:
    """
    Parametrized test for get_uv_version, covering various file contents and expectations.

    Tests get_uv_version with different TOML files and expected results.
    """
    file = tmp_path / filename
    file.write_text(contents)
    result = uv_required_version.get_uv_version(file)
    assert result == expected


def test_get_uv_version_invalid_file(tmp_path: pathlib.Path) -> None:
    """
    Test that get_uv_version raises ValueError for an invalid file.

    Scenario: Invalid file raises ValueError.
    """
    file = tmp_path / "invalid.toml"
    file.write_text("")
    with pytest.raises(ValueError):
        uv_required_version.get_uv_version(file)


@patch("uv_required_version.subprocess.run")
def test_uv_required_version_with_version(
    mock_run: MagicMock, tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """
    Test uv_required_version when a version is specified in the config file.

    Scenario: With version specified in config.
    """
    config = tmp_path / "uv.toml"
    config.write_text("required-version = '==3.4.5'")
    monkeypatch.setattr(uv_required_version, "find_config_file", lambda: config)
    monkeypatch.setattr(
        uv_required_version, "find_uv_binary", lambda: pathlib.Path("/fake/uv")
    )
    monkeypatch.setattr(
        uv_required_version, "get_uv_version", lambda config_file: "uv==3.4.5"
    )
    mock_result = MagicMock(returncode=0)
    mock_run.return_value = mock_result

    result = uv_required_version.uv_required_version(["foo", "--bar"])
    mock_run.assert_called_once()
    args = mock_run.call_args[1]["args"]
    assert args[:4] == ["/fake/uv", "tool", "run", "uv==3.4.5"]
    assert "foo" in args
    assert result is mock_result


@patch("uv_required_version.subprocess.run")
def test_uv_required_version_no_version(
    mock_run: MagicMock, monkeypatch: pytest.MonkeyPatch
) -> None:
    """
    Test uv_required_version when no version is specified in the config file.

    Scenario: No version specified in config.
    """
    monkeypatch.setattr(uv_required_version, "find_config_file", lambda: None)
    monkeypatch.setattr(
        uv_required_version, "find_uv_binary", lambda: pathlib.Path("/fake/uv")
    )
    mock_result = MagicMock(returncode=0)
    mock_run.return_value = mock_result

    result = uv_required_version.uv_required_version(["foo"])
    mock_run.assert_called_once()
    args = mock_run.call_args[1]["args"]
    assert args[0] == "/fake/uv"
    assert "tool" not in args
    assert result is mock_result


@patch("uv_required_version.uv_required_version")
@patch("sys.exit")
def test_cli(mock_exit: MagicMock, mock_uv_required_version: MagicMock) -> None:
    """
    Test the CLI integration with uv_required_version and click.Context.exit.

    Ensures the CLI exits with the correct return code.
    """
    mock_uv_required_version.return_value.returncode = 42
    from uv_required_version import cli

    with patch("sys.argv", ["foo", "bar"]):
        cli()

    mock_exit.assert_called_once_with(42)


def test_get_uv_version_toml_parsing(
    tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """
    Test that get_uv_version uses TOML parsing logic as expected.

    Scenario: TOML parsing logic is invoked and used.
    """
    file = tmp_path / "uv.toml"
    file.write_text("required-version = '==1.2.3'")
    called: dict[str, str] = {}

    def fake_loads(content: str) -> dict[str, str]:
        called["content"] = content
        return {"required-version": "==1.2.3"}

    monkeypatch.setattr(
        uv_required_version, "tomllib", types.SimpleNamespace(loads=fake_loads)
    )
    result = uv_required_version.get_uv_version(file)
    assert called["content"] == "required-version = '==1.2.3'"
    assert result == "uv==1.2.3"


@patch("sys.exit")
@pytest.mark.parametrize(
    "uv_version",
    [
        "==0.7.18",
        "0.7.18",
        "==0.7.0",
        "==0.6.0",
    ],
)
def test_integration(
    mock_exit: MagicMock,
    uv_version: str,
    tmp_path: pathlib.Path,
    monkeypatch: pytest.MonkeyPatch,
    capsys: pytest.CaptureFixture,
) -> None:
    """
    Test the integration of all components in uv_required_version.

    This test ensures that find_config_file, get_uv_version, and find_uv_binary work together.
    """
    monkeypatch.chdir(tmp_path)
    config = tmp_path / "uv.toml"
    config.write_text(f'required-version = "{uv_version}"')
    monkeypatch.setattr("sys.argv", ["uv_required_version", "--version"])
    monkeypatch.setenv("LOG_LEVEL", "DEBUG")
    result = uv_required_version.cli(capture_output=True)
    _, err = capsys.readouterr()
    mock_exit.assert_called_once_with(0)
    uv_version = "==" + uv_version.replace("==", "")
    assert err == f"\x1b[1;33muv-required-version: uv{uv_version}\x1b[0m\n"
    assert result.stdout.decode().startswith(f"uv {uv_version.replace('==', '')}")
    assert result.returncode == 0

[coderabbitai]

Coding Plan

Summary

• Pin uv to a specific version (>= 0.10.5) in the CI workflow to prevent future breaking changes from automatic version updates
• Regenerate all pylock.toml files with the pinned uv version so committed files match what CI generates
• The new filtered pylock.toml files are functionally correct—the removed wheels were never needed for Linux-only container builds

Implementation Steps

Resolve CI Failures and Prevent Future Breakage

This phase addresses both the immediate CI failure and prevents future issues by pinning the uv version and regenerating the affected pylock.toml files with the new uv behavior.

Task 1: Pin uv Version in CI Workflow

Pin the uv version in the CI workflow to prevent unexpected behavior changes when new uv versions are released.

• Update .github/workflows/code-quality.yaml in the check-generated-code job's astral-sh/setup-uv@v7 step to change version: "latest" to version: "0.10.6" (or a specific version >= 0.10.5)
• Update the same workflow's pytest-tests job to use the same pinned version for consistency within the workflow
• The pinned version should be >= 0.10.5 to include the wheel filtering behavior change from PR #18081

Task 2: Regenerate pylock.toml Files

Regenerate all pylock.toml files using uv >= 0.10.5 to incorporate the new filtering behavior that removes unnecessary wheels (macOS/Windows platforms, older Python versions, unreachable architectures).

• Ensure local uv installation is version 0.10.5 or higher before regenerating
• Run bash ci/generate_code.sh from the repository root to regenerate all code including pylock.toml files
• The following six files will be updated with filtered wheel lists:
  • codeserver/ubi9-python-3.12/uv.lock.d/pylock.cpu.toml
  • jupyter/datascience/ubi9-python-3.12/uv.lock.d/pylock.cpu.toml
  • jupyter/rocm/tensorflow/ubi9-python-3.12/pylock.toml
  • jupyter/trustyai/ubi9-python-3.12/uv.lock.d/pylock.cpu.toml
  • runtimes/datascience/ubi9-python-3.12/uv.lock.d/pylock.cpu.toml
  • runtimes/rocm-tensorflow/ubi9-python-3.12/pylock.toml
• The regenerated files will have wheels filtered by requires-python (removing cp39/cp310/cp311 wheels) and platform marker disjointness (removing macOS/Windows/unreachable architecture wheels)

🤖 Prompt for AI agents

This phase resolves the CI failure caused by uv 0.10.5's changed wheel filtering
behavior and prevents future breakage by pinning the uv version.

**Pin uv version in CI workflow:**
- Open `.github/workflows/code-quality.yaml`
- Locate the `check-generated-code` job and find the `astral-sh/setup-uv@v7`
step
- Change the `version` parameter from `"latest"` to `"0.10.6"` (or another
specific version >= 0.10.5)
- Locate the `pytest-tests` job and update its `astral-sh/setup-uv@v7` step to
use the same pinned version for consistency
- The pinned version must be >= 0.10.5 to include the wheel filtering behavior
change from PR `#18081`

**Regenerate pylock.toml files:**
- Verify that your local uv installation is version 0.10.5 or higher
- Execute `bash ci/generate_code.sh` from the repository root directory
- This will regenerate all pylock.toml files with the new uv filtering behavior
- Six specific files will be updated with filtered wheel lists:
  - `codeserver/ubi9-python-3.12/uv.lock.d/pylock.cpu.toml`
  - `jupyter/datascience/ubi9-python-3.12/uv.lock.d/pylock.cpu.toml`
  - `jupyter/rocm/tensorflow/ubi9-python-3.12/pylock.toml`
  - `jupyter/trustyai/ubi9-python-3.12/uv.lock.d/pylock.cpu.toml`
  - `runtimes/datascience/ubi9-python-3.12/uv.lock.d/pylock.cpu.toml`
  - `runtimes/rocm-tensorflow/ubi9-python-3.12/pylock.toml`
- The regenerated files will have wheels filtered by `requires-python` (removing
cp39/cp310/cp311 wheels) and platform marker disjointness (removing
macOS/Windows/unreachable architecture wheels)
- Commit all modified files

Research

The CI workflow in .github/workflows/code-quality.yaml uses astral-sh/setup-uv@v7 with version: "latest" to install uv, then runs ci/generate_code.sh which orchestrates pylock.toml generation via scripts/pylocks_generator.sh. The pylocks_generator script uses uv pip compile --universal --format pylock.toml to generate lock files. The six failing files follow two patterns: four use the uv.lock.d/pylock.cpu.toml structure (codeserver, jupyter/datascience, jupyter/trustyai, runtimes/datascience), and two use direct pylock.toml files (jupyter/rocm/tensorflow, runtimes/rocm-tensorflow).

---

🚀 Next Steps

🤖 All AI agent prompts combined

This phase resolves the CI failure caused by uv 0.10.5's changed wheel filtering
behavior and prevents future breakage by pinning the uv version.

**Pin uv version in CI workflow:**
- Open `.github/workflows/code-quality.yaml`
- Locate the `check-generated-code` job and find the `astral-sh/setup-uv@v7`
step
- Change the `version` parameter from `"latest"` to `"0.10.6"` (or another
specific version >= 0.10.5)
- Locate the `pytest-tests` job and update its `astral-sh/setup-uv@v7` step to
use the same pinned version for consistency
- The pinned version must be >= 0.10.5 to include the wheel filtering behavior
change from PR `#18081`

**Regenerate pylock.toml files:**
- Verify that your local uv installation is version 0.10.5 or higher
- Execute `bash ci/generate_code.sh` from the repository root directory
- This will regenerate all pylock.toml files with the new uv filtering behavior
- Six specific files will be updated with filtered wheel lists:
  - `codeserver/ubi9-python-3.12/uv.lock.d/pylock.cpu.toml`
  - `jupyter/datascience/ubi9-python-3.12/uv.lock.d/pylock.cpu.toml`
  - `jupyter/rocm/tensorflow/ubi9-python-3.12/pylock.toml`
  - `jupyter/trustyai/ubi9-python-3.12/uv.lock.d/pylock.cpu.toml`
  - `runtimes/datascience/ubi9-python-3.12/uv.lock.d/pylock.cpu.toml`
  - `runtimes/rocm-tensorflow/ubi9-python-3.12/pylock.toml`
- The regenerated files will have wheels filtered by `requires-python` (removing
cp39/cp310/cp311 wheels) and platform marker disjointness (removing
macOS/Windows/unreachable architecture wheels)
- Commit all modified files

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[jiridanek]

@coderabbitai can I tell devs to use

uv tool uv

or

uv run uv

and somewhere configure the tool version for uv to be used in the project?

[coderabbitai]

🧩 Analysis chain

🌐 Web query:

uv tool run uv version management self

💡 Result:

uv tool run (aka uvx)

• Run a CLI tool from a Python package without installing it globally (it runs in an isolated, cached environment):
  • uv tool run ruff --version
  • Equivalent shorthand: uvx ruff --version (same behavior). [1]
• Run a specific tool version / refresh to latest:
  • uvx ruff@0.6.0 --version
  • uvx ruff@latest --version (forces a latest check and refreshes the cached tool). [1]
• If you install a tool, it’s put on your PATH (still isolated, but persistent):
  • uv tool install ruff
  • Manage installed tools: uv tool list, uv tool upgrade, uv tool uninstall. [5]

Python version management (interpreters)

• List / install / pin Python versions:
  • uv python list
  • uv python install 3.12 (or 3.12.3, or constraints like '>=3.8,<3.10')
  • uv python pin 3.12 (writes a .python-version; use --global for user config). [3]
• Upgrade uv-managed Python versions:
  • uv python upgrade 3.12 (or upgrade all with uv python upgrade). [3]

uv self version / uv self update (uv’s own version)

• Check your installed uv version:
  • uv self version
  • Also works: uv --version (same output), uv -V (shorter). [2]
• Update uv itself (works when uv was installed via Astral’s standalone installer):
  • uv self update. [4]

Sources: uv tools docs [1], uv “getting help” (version) docs [2], uv Python versions docs [3], uv GitHub README (self update) [4], uv CLI reference (tool subcommands) [5].

---

🌐 Web query:

uv run command tool version configuration

💡 Result:

uv run: project environment + Python version

• uv run ... runs your command inside the project environment (managed from pyproject.toml + uv.lock) and will keep the lockfile and environment in sync before running. [1]
• Configure project-level uv settings in pyproject.toml under [tool.uv] (or in a uv.toml). uv searches upward from the current directory for these files. [2]
• Configure / constrain the Python interpreter version primarily via:
  • [project] requires-python = "..." in pyproject.toml (project requirement). [3]
  • A pinned interpreter in .python-version (commonly managed via uv python pin ...). [4]
  • Override per command with uv run --python <version> ... (requests a specific interpreter). [5]

Tool/package “run” with a specific tool version (recommended: uvx / uv tool run)

If what you mean by “tool version configuration” is “run ruff/black/mypy/etc. at a specific version”:

• Use uvx (alias of uv tool run) and request a version with @:
  • uvx ruff@0.6.0 --version [6]
  • uv tool run ruff@0.6.0 --version [7]
• To refresh to the newest release explicitly:
  • uvx ruff@latest ... [6]
• Behavior notes:
  • uvx caches tool environments; it will reuse cached versions unless you request a different one or refresh. [6]
  • If you previously did uv tool install ruff, then uvx ruff will default to the installed version (unless you request a version or use --isolated). [6][7]
• Important config scope rule: for uv tool ... commands, local project config is ignored; they read user/system configuration (e.g., ~/.config/uv/uv.toml). [2]

If you tell me whether you mean (A) Python interpreter version for uv run, or (B) the version of a CLI tool you’re executing (ruff/black/etc.), I can give the exact commands + where to put the config for your setup.

---

@jiridanek Great question! Here's what's possible:

✅ Yes: Explicit version with uvx

Developers can use:

uvx uv@0.10.6 lock
uvx uv@0.10.6 sync
# or the full form:
uv tool run uv@0.10.6 lock

This runs uv 0.10.6 in an isolated, cached environment regardless of what's installed system-wide. It works perfectly with Homebrew-managed uv or any other installation method.

❌ No: Automatic version from project config

However, there's no native way to configure this in uv.toml or pyproject.toml such that running uvx uv (without the version) automatically picks up the project's required-version.

Here's why:

• uv tool run ignores local project config (uv.toml, pyproject.toml) and only reads user/system config like ~/.config/uv/uv.toml
• The required-version setting enforces the version when uv runs, but it doesn't tell uvx which version to use
• uv run is for running commands in your project environment (Python packages), not for managing uv's own version

The gap

You want:

# Developer runs this (no version specified)
uvx uv lock

# And it automatically uses 0.10.6 because uv.toml says:
required-version = "==0.10.6"

This doesn't exist natively. That's exactly the problem the uv-required-version wrapper solves.

Recommendation: Vendor the wrapper

Given your Homebrew constraint and DX requirements, vendoring the wrapper is the right call:

1. Add the uv_required_version.py script (and tests) to your repo, e.g., in scripts/
2. Update CONTRIBUTING.md to tell developers:

   # Use the wrapper instead of uv directly
   python scripts/uv_required_version.py lock
   python scripts/uv_required_version.py sync

3. The wrapper reads required-version from uv.toml and automatically runs uvx uv@0.10.6 under the hood

Alternative (simpler but less automatic): Document the explicit version command:

## uv version requirement

This project requires uv 0.10.6. If you have a different version:

```bash
uvx uv@0.10.6 lock
uvx uv@0.10.6 sync

This approach works but shifts the responsibility to developers to remember the `@0.10.6` suffix.

The native auto-detection you're looking for is tracked in [astral-sh/uv#11065](https://github.com/astral-sh/uv/issues/11065) — when implemented, `uvx uv` would automatically run the version specified in `required-version`. Until then, vendoring the wrapper gives you the best DX.


<!-- <agentComponentType>chat-answer</agentComponentType> -->

<!-- <rawResChunk><answer><details>
<summary>🧩 Analysis chain</summary>

🌐 Web query:

```web
uv tool run uv version management self

💡 Result:

uv tool run (aka uvx)

• Run a CLI tool from a Python package without installing it globally (it runs in an isolated, cached environment):
  • uv tool run ruff --version
  • Equivalent shorthand: uvx ruff --version (same behavior). [1]
• Run a specific tool version / refresh to latest:
  • uvx ruff@0.6.0 --version
  • uvx ruff@latest --version (forces a latest check and refreshes the cached tool). [1]
• If you install a tool, it’s put on your PATH (still isolated, but persistent):
  • uv tool install ruff
  • Manage installed tools: uv tool list, uv tool upgrade, uv tool uninstall. [5]

Python version management (interpreters)

• List / install / pin Python versions:
  • uv python list
  • uv python install 3.12 (or 3.12.3, or constraints like '>=3.8,<3.10')
  • uv python pin 3.12 (writes a .python-version; use --global for user config). [3]
• Upgrade uv-managed Python versions:
  • uv python upgrade 3.12 (or upgrade all with uv python upgrade). [3]

uv self version / uv self update (uv’s own version)

• Check your installed uv version:
  • uv self version
  • Also works: uv --version (same output), uv -V (shorter). [2]
• Update uv itself (works when uv was installed via Astral’s standalone installer):
  • uv self update. [4]

Sources: uv tools docs [1], uv “getting help” (version) docs [2], uv Python versions docs [3], uv GitHub README (self update) [4], uv CLI reference (tool subcommands) [5].

---

🌐 Web query:

uv run command tool version configuration

💡 Result:

uv run: project environment + Python version

• uv run ... runs your command inside the project environment (managed from pyproject.toml + uv.lock) and will keep the lockfile and environment in sync before running. [1]
• Configure project-level uv settings in pyproject.toml under [tool.uv] (or in a uv.toml). uv searches upward from the current directory for these files. [2]
• Configure / constrain the Python interpreter version primarily via:
  • [project] requires-python = "..." in pyproject.toml (project requirement). [3]
  • A pinned interpreter in .python-version (commonly managed via uv python pin ...). [4]
  • Override per command with uv run --python <version> ... (requests a specific interpreter). [5]

Tool/package “run” with a specific tool version (recommended: uvx / uv tool run)

If what you mean by “tool version configuration” is “run ruff/black/mypy/etc. at a specific version”:

• Use uvx (alias of uv tool run) and request a version with @:
  • uvx ruff@0.6.0 --version [6]
  • uv tool run ruff@0.6.0 --version [7]
• To refresh to the newest release explicitly:
  • uvx ruff@latest ... [6]
• Behavior notes:
  • uvx caches tool environments; it will reuse cached versions unless you request a different one or refresh. [6]
  • If you previously did uv tool install ruff, then uvx ruff will default to the installed version (unless you request a version or use --isolated). [6][7]
• Important config scope rule: for uv tool ... commands, local project config is ignored; they read user/system configuration (e.g., ~/.config/uv/uv.toml). [2]

If you tell me whether you mean (A) Python interpreter version for uv run, or (B) the version of a CLI tool you’re executing (ruff/black/etc.), I can give the exact commands + where to put the config for your setup.

---

@jiridanek Great question! Here's what's possible:

✅ Yes: Explicit version with uvx

Developers can use:

uvx uv@0.10.6 lock
uvx uv@0.10.6 sync
# or the full form:
uv tool run uv@0.10.6 lock

This runs uv 0.10.6 in an isolated, cached environment regardless of what's installed system-wide. It works perfectly with Homebrew-managed uv or any other installation method.

❌ No: Automatic version from project config

However, there's no native way to configure this in uv.toml or pyproject.toml such that running uvx uv (without the version) automatically picks up the project's required-version.

Here's why:

• uv tool run ignores local project config (uv.toml, pyproject.toml) and only reads user/system config like ~/.config/uv/uv.toml
• The required-version setting enforces the version when uv runs, but it doesn't tell uvx which version to use
• uv run is for running commands in your project environment (Python packages), not for managing uv's own version

The gap

You want:

# Developer runs this (no version specified)
uvx uv lock

# And it automatically uses 0.10.6 because uv.toml says:
required-version = "==0.10.6"

This doesn't exist natively. That's exactly the problem the uv-required-version wrapper solves.

Recommendation: Vendor the wrapper

Given your Homebrew constraint and DX requirements, vendoring the wrapper is the right call:

1. Add the uv_required_version.py script (and tests) to your repo, e.g., in scripts/
2. Update CONTRIBUTING.md to tell developers:

   # Use the wrapper instead of uv directly
   python scripts/uv_required_version.py lock
   python scripts/uv_required_version.py sync

3. The wrapper reads required-version from uv.toml and automatically runs uvx uv@0.10.6 under the hood

Alternative (simpler but less automatic): Document the explicit version command:

## uv version requirement

This project requires uv 0.10.6. If you have a different version:

```bash
uvx uv@0.10.6 lock
uvx uv@0.10.6 sync

This approach works but shifts the responsibility to developers to remember the `@0.10.6` suffix.

The native auto-detection you're looking for is tracked in [astral-sh/uv#11065](https://github.com/astral-sh/uv/issues/11065) — when implemented, `uvx uv` would automatically run the version specified in `required-version`. Until then, vendoring the wrapper gives you the best DX.</answer></rawResChunk> -->