Add a Python architecture input

chore: update known checksums for 0.12.20

Co-authored-by: eifinger <1481961+eifinger@users.noreply.github.com>

.agents/skills/dependabot-pr-rollup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dependabot-pr-rollup
-description: Find open Dependabot PRs for the current GitHub repo, compare each PR head to its base branch, replay only the net dependency changes in a fresh worktree and branch, run npm validation, and optionally commit, push, and open a PR. Use when you want to batch or manually replicate active Dependabot updates.
+description: Find open Dependabot PRs for the current GitHub repo, compare each PR head to its base branch, replay only the net dependency changes in a fresh worktree and branch, run npm validation, then commit, push, and open a pull request labeled dependencies. Use when you want to batch or manually replicate active Dependabot updates.
 license: MIT
 compatibility: Requires git, git worktree, gh CLI auth, npm, and a GitHub repo with an origin remote.
 ---
@@ -13,7 +13,7 @@ Use this skill when the user wants to:
 - find all open Dependabot PRs in the current repo
 - reproduce their net effect in one local branch
 - validate the result with the repo's standard npm checks
-- optionally commit, push, and open a PR
+- commit and push the validated changes, then open a PR labeled `dependencies`
 
 ## Workflow
 
@@ -28,7 +28,8 @@ Use this skill when the user wants to:
    - Use `npm install ... --ignore-scripts` for direct dependency changes so `package-lock.json` stays in sync.
    - When updating `@biomejs/biome`, also update the Biome schema URL version in `biome.json` to match the installed Biome version.
 7. Run `npm run all`.
-8. If requested, commit the changed source, lockfile, and generated artifacts, then push and open a PR.
+8. Commit the changed source, lockfile, and generated artifacts, then push the branch.
+9. Always open a pull request for the rollup and add the `dependencies` label to it. Pass `--label dependencies` to `gh pr create`, or add the label immediately afterward with `gh pr edit --add-label dependencies`.
 
 ## Repo-specific notes
 
@@ -46,4 +47,5 @@ Always report:
 - new worktree path
 - files changed
 - `npm run all` result
-- if applicable, commit SHA and PR URL
+- commit SHA and PR URL
+- confirmation that the PR has the `dependencies` label

.gitattributes

@@ -1,2 +1,3 @@
 * text=auto eol=lf
 dist/** -diff linguist-generated=true
+src/download/checksum/known-checksums.json linguist-generated=true

.github/actionlint.yaml

@@ -8,6 +8,10 @@ self-hosted-runner:
 # Empty array means no configuration variable is allowed.
 config-variables: null
 paths:
+  .github/workflows/**/*.{yml,yaml}:
+    ignore:
+      - 'specifying action "\$/" in invalid format because ref is missing'
+      - 'reusable workflow call "\$/.+" at "uses" is not following the format'
   .github/workflows/test.yml:
     ignore:
       - 'invalid runner name.+'

.github/dependabot.yml

@@ -5,11 +5,11 @@ updates:
     schedule:
       interval: daily
     cooldown:
-      default-days: 7
+      default-days: 30
 
   - package-ecosystem: npm
     directory: /
     schedule:
       interval: daily
     cooldown:
-      default-days: 7
+      default-days: 30

.github/workflows/codeql-analysis.yml

@@ -41,13 +41,13 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
         with:
           languages: ${{ matrix.language }}
           source-root: src
@@ -59,7 +59,7 @@ jobs:
       # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        uses: github/codeql-action/autobuild@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
 
       # ℹ️ Command-line programs to run using the OS shell.
       # 📚 https://git.io/JvXDl
@@ -73,4 +73,4 @@ jobs:
       #   make release
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7

.github/workflows/release-drafter.yml

@@ -19,7 +19,7 @@ jobs:
       pull-requests: read
     steps:
       - name: 🚀 Run Release Drafter
-        uses: release-drafter/release-drafter@4d75298e00d9e34c483e5ff8c68d0ea1c1940c1e # v7.5.1
+        uses: release-drafter/release-drafter@34d80673e067bdc0c24568d3af899c216adcfaa9 # v7.7.0
         with:
           commitish: ${{ github.sha }}
         env:

.github/workflows/release.yml

@@ -116,7 +116,7 @@ jobs:
     name: Update docs
     needs:
       - release
-    uses: ./.github/workflows/update-docs.yml
+    uses: $/.github/workflows/update-docs.yml
     permissions:
       contents: write
       pull-requests: write

.github/workflows/test.yml

@@ -21,14 +21,14 @@ jobs:
     permissions:
       security-events: write # for zizmor
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Actionlint
         uses: eifinger/actionlint-action@1fc89649be682d16ec5cf65ea16e269eb88d3982 # v1.10.2
       - name: Run zizmor
-        uses: zizmorcore/zizmor-action@5f14fd08f7cf1cb1609c1e344975f152c7ee938d # v0.5.6
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: zizmorcore/zizmor-action@70fb788f84895a7701f5643d103d587e460b5c99 # v0.6.3
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: .nvmrc
           cache: npm
@@ -51,12 +51,12 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, macos-14, windows-latest]
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Install latest version
         id: setup-uv
-        uses: ./
+        uses: $/
       - run: uv sync
         working-directory: __tests__/fixtures/uv-project
         shell: bash
@@ -76,12 +76,12 @@ jobs:
   test-uv-no-modify-path:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Install with UV_NO_MODIFY_PATH set
         id: setup-uv
-        uses: ./
+        uses: $/
         env:
           UV_NO_MODIFY_PATH: 1
       - run: |
@@ -125,12 +125,12 @@ jobs:
             expected-version: "0.1.0"
             resolution-strategy: "lowest"
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Install version ${{ matrix.input.version-input }} with strategy ${{ matrix.input.resolution-strategy || 'highest' }}
         id: setup-uv
-        uses: ./
+        uses: $/
         with:
           version: ${{ matrix.input.version-input }}
           resolution-strategy: ${{ matrix.input.resolution-strategy || 'highest' }}
@@ -154,11 +154,8 @@ jobs:
       matrix:
         version-input: ["latest", ">=0.8"]
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
       - name: Install version ${{ matrix.version-input }}
-        uses: ./
+        uses: $/
         with:
           version: ${{ matrix.version-input }}
       - name: Latest version gets installed
@@ -194,11 +191,11 @@ jobs:
           - working-directory: "__tests__/fixtures/uv-toml-project"
             expected-version: "0.5.15"
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Install version from ${{ matrix.input.working-directory }}
-        uses: ./
+        uses: $/
         with:
           working-directory: ${{ matrix.input.working-directory }}
       - name: Correct version gets installed
@@ -220,11 +217,11 @@ jobs:
           - version-file: "__tests__/fixtures/.tool-versions"
             expected-version: "0.5.15"
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Install version from ${{ matrix.input.version-file }}
-        uses: ./
+        uses: $/
         with:
           version-file: ${{ matrix.input.version-file }}
       - name: Correct version gets installed
@@ -234,15 +231,40 @@ jobs:
             exit 1
           fi
 
+  test-tool-versions-python-version:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install versions from .tool-versions
+        id: setup-uv
+        uses: $/
+        with:
+          version-file: "__tests__/fixtures/.tool-versions"
+      - name: Verify Python version from .tool-versions
+        run: |
+          if [ "$UV_PYTHON" != "3.13.1t" ]; then
+            echo "Wrong UV_PYTHON: $UV_PYTHON"
+            exit 1
+          fi
+          if [ "$PYTHON_VERSION" != "3.13.1t" ]; then
+            echo "Wrong python-version output: $PYTHON_VERSION"
+            exit 1
+          fi
+        shell: bash
+        env:
+          PYTHON_VERSION: ${{ steps.setup-uv.outputs.python-version }}
+
   test-malformed-pyproject-file-fallback:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Install using malformed pyproject.toml
         id: setup-uv
-        uses: ./
+        uses: $/
         with:
           working-directory: "__tests__/fixtures/malformed-pyproject-toml-project"
       - run: uv --help
@@ -257,11 +279,11 @@ jobs:
           - os: macos-latest
             checksum: "a70cbfbf3bb5c08b2f84963b4f12c94e08fbb2468ba418a3bfe1066fbe9e7218"
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Checksum matches expected
-        uses: ./
+        uses: $/
         with:
           version: "0.3.2"
           checksum: ${{ matrix.inputs.checksum }}
@@ -271,11 +293,11 @@ jobs:
   test-with-explicit-token:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Install default version
-        uses: ./
+        uses: $/
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
       - run: uv sync
@@ -284,12 +306,9 @@ jobs:
   test-uvx:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
       - name: Install default version
-        uses: ./
-      - run: uvx ruff --version
+        uses: $/
+      - run: uvx ruff@0.14.10 --version
 
   test-tool-install:
     runs-on: ${{ matrix.os }}
@@ -297,12 +316,9 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, macos-14, windows-latest]
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
       - name: Install default version
-        uses: ./
-      - run: uv tool install ruff
+        uses: $/
+      - run: uv tool install ruff==0.14.10
       - run: ruff --version
 
   test-python-version:
@@ -311,12 +327,12 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Install latest version
         id: setup-uv
-        uses: ./
+        uses: $/
         with:
           python-version: 3.13.1t
       - name: Verify UV_PYTHON is set to correct version
@@ -331,9 +347,14 @@ jobs:
           if [ "$PYTHON_VERSION" != "3.13.1t" ]; then
             exit 1
           fi
+          if [ -n "$PYTHON_RUNTIME_ID" ]; then
+            echo "python-runtime-id should be empty without environment activation"
+            exit 1
+          fi
         shell: bash
         env:
           PYTHON_VERSION: ${{ steps.setup-uv.outputs.python-version }}
+          PYTHON_RUNTIME_ID: ${{ steps.setup-uv.outputs.python-runtime-id }}
       - run: uv sync
         working-directory: __tests__/fixtures/uv-project
 
@@ -343,12 +364,9 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
       - name: Install latest version
         id: setup-uv
-        uses: ./
+        uses: $/
         with:
           python-version: 3.13.1t
           activate-environment: true
@@ -382,12 +400,9 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
       - name: Install latest version
         id: setup-uv
-        uses: ./
+        uses: $/
         with:
           python-version: 3.13.1t
           activate-environment: true
@@ -429,13 +444,19 @@ jobs:
               raise SystemExit(f"Python is not running from custom venv: {sys.executable}")
           PY
         shell: bash
+      - name: Verify Python runtime ID from custom venv
+        run: |
+          case "$PYTHON_RUNTIME_ID" in
+            cpython-3.13.1+freethreaded-*) ;;
+            *) echo "Wrong Python runtime ID: $PYTHON_RUNTIME_ID"; exit 1 ;;
+          esac
+        shell: bash
+        env:
+          PYTHON_RUNTIME_ID: ${{ steps.setup-uv.outputs.python-runtime-id }}
 
   test-activate-environment-no-project:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
       - name: Create incompatible pyproject.toml
         run: |
           cat > pyproject.toml <<'EOF'
@@ -451,7 +472,7 @@ jobs:
         shell: bash
       - name: Install latest version with no-project
         id: setup-uv
-        uses: ./
+        uses: $/
         with:
           python-version: 3.13.1t
           activate-environment: true
@@ -477,11 +498,11 @@ jobs:
     runs-on: ubuntu-latest
     container: debian:unstable
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Install latest version
-        uses: ./
+        uses: $/
         with:
           enable-cache: true
       - run: uv sync
@@ -489,14 +510,14 @@ jobs:
 
   test-musl:
     runs-on: ubuntu-latest
-    container: alpine
+    container: alpine@sha256:28bd5fe8b56d1bd048e5babf5b10710ebe0bae67db86916198a6eec434943f8b # 3.24.1
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Install latest version
         id: setup-uv
-        uses: ./
+        uses: $/
         with:
           enable-cache: true
       - name: Verify cache key contains alpine
@@ -530,12 +551,9 @@ jobs:
           - os: windows-2025
             expected-os: "windows-2025"
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
       - name: Setup uv
         id: setup-uv
-        uses: ./
+        uses: $/
         with:
           enable-cache: true
       - name: Verify cache key contains OS version
@@ -556,11 +574,11 @@ jobs:
         enable-cache: ["true", "false", "auto"]
         os: ["ubuntu-latest", "windows-latest"]
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Setup with cache
-        uses: ./
+        uses: $/
         with:
           enable-cache: ${{ matrix.enable-cache }}
           cache-suffix: ${{ github.run_id }}-${{ github.run_attempt }}-test-setup-cache-${{ matrix.os }}-${{ matrix.enable-cache }}
@@ -575,12 +593,12 @@ jobs:
         os: ["ubuntu-latest", "windows-latest"]
     needs: test-setup-cache
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Restore with cache
         id: restore
-        uses: ./
+        uses: $/
         with:
           enable-cache: ${{ matrix.enable-cache }}
           cache-suffix: ${{ github.run_id }}-${{ github.run_attempt }}-test-setup-cache-${{ matrix.os }}-${{ matrix.enable-cache }}
@@ -609,11 +627,11 @@ jobs:
   test-setup-cache-requirements-txt:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Setup with cache
-        uses: ./
+        uses: $/
         with:
           enable-cache: true
           cache-suffix: ${{ github.run_id }}-${{ github.run_attempt }}-test-setup-cache-requirements-txt
@@ -625,12 +643,12 @@ jobs:
     runs-on: ubuntu-latest
     needs: test-setup-cache-requirements-txt
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Restore with cache
         id: restore
-        uses: ./
+        uses: $/
         with:
           enable-cache: true
           cache-suffix: ${{ github.run_id }}-${{ github.run_attempt }}-test-setup-cache-requirements-txt
@@ -649,11 +667,11 @@ jobs:
   test-setup-cache-dependency-glob:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Setup with cache
-        uses: ./
+        uses: $/
         with:
           enable-cache: true
           cache-dependency-glob: |
@@ -666,7 +684,7 @@ jobs:
     runs-on: ubuntu-latest
     needs: test-setup-cache-dependency-glob
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Change pyproject.toml
@@ -675,7 +693,7 @@ jobs:
           echo 'dev-dependencies = []' >> __tests__/fixtures/uv-project/pyproject.toml
       - name: Restore with cache
         id: restore
-        uses: ./
+        uses: $/
         with:
           enable-cache: true
           cache-dependency-glob: |
@@ -694,11 +712,11 @@ jobs:
   test-setup-cache-save-cache-false:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Setup with cache
-        uses: ./
+        uses: $/
         with:
           enable-cache: true
           save-cache: false
@@ -710,12 +728,12 @@ jobs:
     runs-on: ubuntu-latest
     needs: test-setup-cache-save-cache-false
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Restore with cache
         id: restore
-        uses: ./
+        uses: $/
         with:
           enable-cache: true
           cache-suffix: ${{ github.run_id }}-${{ github.run_attempt }}-test-setup-cache-save-cache-false
@@ -730,11 +748,11 @@ jobs:
   test-setup-cache-restore-cache-false:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Setup with cache
-        uses: ./
+        uses: $/
         with:
           enable-cache: true
           cache-suffix: ${{ github.run_id }}-${{ github.run_attempt }}-test-setup-cache-restore-cache-false
@@ -745,12 +763,12 @@ jobs:
     runs-on: ubuntu-latest
     needs: test-setup-cache-restore-cache-false
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Restore with cache
         id: restore
-        uses: ./
+        uses: $/
         with:
           enable-cache: true
           restore-cache: false
@@ -773,11 +791,8 @@ jobs:
             expected-cache-dir: "D:\\a\\_temp\\setup-uv-cache"
     runs-on: ${{ matrix.inputs.os }}
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
       - name: Setup with cache
-        uses: ./
+        uses: $/
         with:
           enable-cache: true
           cache-suffix: ${{ github.run_id }}-${{ github.run_attempt }}-test-cache-local
@@ -791,11 +806,8 @@ jobs:
   test-cache-local-cache-disabled:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
       - name: Setup without cache
-        uses: ./
+        uses: $/
         with:
           enable-cache: false
 
@@ -810,11 +822,8 @@ jobs:
   test-cache-local-cache-disabled-but-explicit-path:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
       - name: Setup without cache
-        uses: ./
+        uses: $/
         with:
           enable-cache: false
           cache-local-path: /tmp/uv-cache-disabled
@@ -830,13 +839,13 @@ jobs:
   test-no-python-version:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Fake pyproject.toml at root
         run: cp __tests__/fixtures/old-python-constraint-project/pyproject.toml pyproject.toml
       - name: Setup with cache
-        uses: ./
+        uses: $/
         with:
           enable-cache: true
       - run: uv sync
@@ -845,11 +854,11 @@ jobs:
   test-custom-manifest-file:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Install from custom manifest file
-        uses: ./
+        uses: $/
         with:
           manifest-file: "https://raw.githubusercontent.com/astral-sh/setup-uv/${{ github.ref }}/__tests__/download/custom-manifest.ndjson"
       - run: uv sync
@@ -864,12 +873,9 @@ jobs:
   test-download-from-astral-mirror-false:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
       - name: Install with download-from-astral-mirror disabled
         id: setup-uv
-        uses: ./
+        uses: $/
         with:
           download-from-astral-mirror: false
       - name: Verify uv is installed
@@ -878,14 +884,11 @@ jobs:
   test-absolute-path:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
       - name: Create requirements.txt
         run: echo "uv==0.6.17" > /tmp/setup-uv-requirements.txt
       - name: Install from requirements file
         id: setup-uv
-        uses: ./
+        uses: $/
         with:
           version-file: "/tmp/setup-uv-requirements.txt"
       - name: Correct version gets installed
@@ -898,16 +901,13 @@ jobs:
   test-relative-path:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
       - name: mkdir
         run: mkdir -p /tmp/setup-uv-test-relative-path
       - name: Create requirements.txt
         run: echo "uv==0.6.17" > /tmp/setup-uv-test-relative-path/setup-uv-requirements.txt
       - name: Install from requirements file
         id: setup-uv
-        uses: ./
+        uses: $/
         with:
           version-file: "./setup-uv-requirements.txt"
           working-directory: "/tmp/setup-uv-test-relative-path"
@@ -922,11 +922,11 @@ jobs:
   test-cache-prune-force:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Setup uv
-        uses: ./
+        uses: $/
         with:
           cache-suffix: ${{ github.run_id }}-${{ github.run_attempt }}-test-cache-prune-force
       - name: Create long running python script
@@ -939,7 +939,7 @@ jobs:
   test-cache-dir-from-file:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Verify uv cache dir is not populated
@@ -949,7 +949,7 @@ jobs:
             exit 1
           fi
       - name: Setup uv
-        uses: ./
+        uses: $/
         with:
           working-directory: __tests__/fixtures/cache-dir-defined-project
       - run: uv sync
@@ -966,11 +966,11 @@ jobs:
     env:
       UV_PYTHON_INSTALL_DIR: /tmp/missing-uv-python
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Setup uv with cache and python cache enabled
-        uses: ./
+        uses: $/
         with:
           enable-cache: true
           cache-python: true
@@ -987,7 +987,7 @@ jobs:
   test-cache-python-installs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Verify Python install dir is not populated
@@ -997,7 +997,7 @@ jobs:
             exit 1
           fi
       - name: Setup uv with cache
-        uses: ./
+        uses: $/
         with:
           enable-cache: true
           cache-python: true
@@ -1014,7 +1014,7 @@ jobs:
     runs-on: ubuntu-latest
     needs: test-cache-python-installs
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Verify Python install dir does not exist
@@ -1025,7 +1025,7 @@ jobs:
           fi
       - name: Restore with cache
         id: restore
-        uses: ./
+        uses: $/
         with:
           enable-cache: true
           cache-python: true
@@ -1056,12 +1056,9 @@ jobs:
             expected-python-dir: "D:\\a\\_temp\\uv-python-dir"
     runs-on: ${{ matrix.inputs.os }}
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
       - name: Install latest version
         id: setup-uv
-        uses: ./
+        uses: $/
       - name: Check Python dir is expected dir
         run: |
           if [ "$UV_PYTHON_INSTALL_DIR" != "${{ matrix.inputs.expected-python-dir }}" ]; then
@@ -1072,25 +1069,29 @@ jobs:
       - name: Install python works
         run: uv python install
 
-  test-act:
+  test-workflow-run:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Install act
         run: gh extension install https://github.com/nektos/gh-act
         env:
           GH_TOKEN: ${{ github.token }}
-      - name: Run test-uvx with act
-        run: gh act -j test-uvx -P ubuntu-latest=catthehacker/ubuntu:act-latest
+      - name: Verify workflow_run disables automatic caching with act
+        run: |
+          gh act workflow_run \
+            -W __tests__/workflows/workflow-run.yml \
+            -P ubuntu-latest=catthehacker/ubuntu:act-latest \
+            --env RUNNER_ENVIRONMENT=github-hosted
         env:
           GH_TOKEN: ${{ github.token }}
 
   validate-typings:
     runs-on: "ubuntu-latest"
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Validate typings
@@ -1107,6 +1108,7 @@ jobs:
       - test-from-working-directory-version
       - test-malformed-pyproject-file-fallback
       - test-version-file-version
+      - test-tool-versions-python-version
       - test-checksum
       - test-with-explicit-token
       - test-uvx
@@ -1142,7 +1144,7 @@ jobs:
       - test-cache-python-installs
       - test-restore-python-installs
       - test-python-install-dir
-      - test-act
+      - test-workflow-run
       - validate-typings
     if: always()
     steps:

.github/workflows/update-docs.yml

@@ -18,7 +18,7 @@ jobs:
       contents: write
       pull-requests: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: true
@@ -60,20 +60,8 @@ jobs:
           else
               echo "changes-exist=false" >> "$GITHUB_OUTPUT"
           fi
-      - name: Commit and push changes
-        if: ${{ steps.changes-exist.outputs.changes-exist == 'true' }}
-        id: commit-and-push
-        continue-on-error: true
-        run: |
-          git config user.name "$GITHUB_ACTOR"
-          git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
-          git add .
-          git commit -m "docs: update version references to $NEW_VERSION"
-          git push origin HEAD:refs/heads/main
-        env:
-          NEW_VERSION: ${{ steps.tag-info.outputs.tag }}
       - name: Create Pull Request
-        if: ${{ steps.changes-exist.outputs.changes-exist == 'true' && steps.commit-and-push.outcome != 'success' }}
+        if: ${{ steps.changes-exist.outputs.changes-exist == 'true' }}
         uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
         with:
           commit-message: "docs: update version references to ${{ steps.tag-info.outputs.tag }}"
@@ -82,6 +70,6 @@ jobs:
             Update `uses: astral-sh/setup-uv@...` references in documentation to
             `${{ steps.tag-info.outputs.sha }} # ${{ steps.tag-info.outputs.tag }}`.
           base: main
-          labels: "automated-pr,update-docs"
+          labels: "automated-pr,documentation"
           branch: update-docs-${{ steps.tag-info.outputs.tag }}
           delete-branch: true

.github/workflows/update-known-checksums.yml

@@ -15,10 +15,10 @@ jobs:
       contents: write
       pull-requests: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: true
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: .nvmrc
           cache: npm
@@ -26,7 +26,7 @@ jobs:
         id: update-known-checksums
         run:
           node dist/update-known-checksums/index.cjs
-          src/download/checksum/known-checksums.ts
+          src/download/checksum/known-checksums.json
       - name: Check for changes
         id: changes-exist
         run: |
@@ -39,21 +39,8 @@ jobs:
       - name: Compile changes
         if: ${{ steps.changes-exist.outputs.changes-exist == 'true' }}
         run: npm ci --ignore-scripts && npm run all
-      - name: Commit and push changes
-        if: ${{ steps.changes-exist.outputs.changes-exist == 'true' }}
-        id: commit-and-push
-        continue-on-error: true
-        run: |
-          git config user.name "$GITHUB_ACTOR"
-          git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
-          git add .
-          git commit -m "chore: update known checksums for $LATEST_VERSION"
-          git push origin HEAD:refs/heads/main
-        env:
-          LATEST_VERSION: ${{ steps.update-known-checksums.outputs.latest-version }}
-
       - name: Create Pull Request
-        if: ${{ steps.changes-exist.outputs.changes-exist == 'true' && steps.commit-and-push.outcome != 'success' }}
+        if: ${{ steps.changes-exist.outputs.changes-exist == 'true' }}
         uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
         with:
           commit-message: "chore: update known checksums"

.npmrc

@@ -0,0 +1,3 @@
+engine-strict = true
+ignore-scripts = true
+min-release-age = 7

.nvmrc

@@ -1 +1 @@
-24
+24.19.0

README.md

@@ -15,6 +15,7 @@ Set up your GitHub Actions workflow with a specific version of [uv](https://docs
   - [Inputs](#inputs)
   - [Outputs](#outputs)
   - [Python version](#python-version)
+  - [Python architecture](#python-architecture)
   - [Working directory](#working-directory)
 - [Advanced Configuration](#advanced-configuration)
 - [How it works](#how-it-works)
@@ -26,7 +27,7 @@ Set up your GitHub Actions workflow with a specific version of [uv](https://docs
 
 ```yaml
 - name: Install the latest version of uv
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
 ```
 
 If you do not specify a version, this action will look for a [required-version](https://docs.astral.sh/uv/reference/settings/#required-version)
@@ -42,20 +43,23 @@ Have a look under [Advanced Configuration](#advanced-configuration) for detailed
 
 ```yaml
 - name: Install uv with all available options
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
-    # The version of uv to install (default: searches for version in config files, then latest)
+    # The version of uv to install, e.g., "0.5.0", "latest", or "latest-known" (default: searches for version in config files, then latest)
     version: ""
 
-    # Path to a file containing the version of uv to install, e.g., uv.toml, pyproject.toml, .tool-versions, requirements.txt or uv.lock (default: searches uv.toml then pyproject.toml)
+    # Path to a file containing the version of uv to install, e.g., uv.toml, pyproject.toml, .tool-versions, requirements.txt or uv.lock. A selected .tool-versions file can also provide the Python version (default: searches uv.toml then pyproject.toml)
     version-file: ""
 
     # Resolution strategy when resolving version ranges: 'highest' or 'lowest'
     resolution-strategy: "highest"
 
-    # The version of Python to set UV_PYTHON to
+    # The version of Python to set UV_PYTHON to (overrides the Python version from .tool-versions)
     python-version: ""
 
+    # The Python architecture to set UV_PYTHON_ARCH to, e.g., x86_64 or aarch64
+    python-arch: ""
+
     # Use uv venv to activate a venv ready to be used by later steps
     activate-environment: "false"
 
@@ -74,7 +78,7 @@ Have a look under [Advanced Configuration](#advanced-configuration) for detailed
     # Used when downloading uv from GitHub releases
     github-token: ${{ github.token }}
 
-    # Enable uploading of the uv cache: true, false, or auto (enabled on GitHub-hosted runners, disabled on self-hosted runners)
+    # Enable the GitHub Actions cache for uv: true, false, or auto (enabled on GitHub-hosted runners except for release, tag push, pull_request_target, and workflow_run events; disabled on self-hosted runners)
     enable-cache: "auto"
 
     # Glob pattern to match files relative to the repository root to control the cache
@@ -90,8 +94,8 @@ Have a look under [Advanced Configuration](#advanced-configuration) for detailed
     # Whether to restore the cache if found
     restore-cache: "true"
 
-    # Whether to save the cache after the run
-    save-cache: "true"
+    # Whether to save the cache after the run: true, false, or auto (disabled for merge_group events)
+    save-cache: "auto"
 
     # Suffix for the cache key
     cache-suffix: ""
@@ -100,7 +104,7 @@ Have a look under [Advanced Configuration](#advanced-configuration) for detailed
     cache-local-path: ""
 
     # Prune cache before saving
-    prune-cache: "true"
+    prune-cache: "false"
 
     # Upload managed Python installations to the GitHub Actions cache
     cache-python: "false"
@@ -138,17 +142,37 @@ Have a look under [Advanced Configuration](#advanced-configuration) for detailed
 - `cache-hit`: A boolean value to indicate a cache entry was found.
 - `venv`: Path to the activated venv if activate-environment is true.
 - `python-version`: The Python version that was set.
+- `python-runtime-id`: An opaque identifier reported by uv for the activated venv's Python runtime. Empty when `activate-environment` is false.
 - `python-cache-hit`: A boolean value to indicate the Python cache entry was found.
 
 ### Python version
 
 You can use the input `python-version` to set the environment variable `UV_PYTHON` for the rest of your workflow
 
-This will override any python version specifications in `pyproject.toml` and `.python-version`
+This will override any python version specifications in `pyproject.toml`, `.python-version`, and
+an explicitly selected `.tool-versions` file.
+
+When `version-file` points to `.tool-versions`, its `python` entry is used if neither
+`python-version` nor `UV_PYTHON` is set:
+
+```text
+uv 0.12.3
+python 3.13
+```
+
+```yaml
+- uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    version-file: ".tool-versions"
+```
+
+Only a single Python version is supported. Filesystem paths are not supported for uv or Python.
+Multiple Python fallback versions and the asdf `ref:`, `path:`, and `system` forms are ignored with
+a warning.
 
 ```yaml
 - name: Install the latest version of uv and set the python version to 3.13t
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     python-version: 3.13t
 - run: uv pip install --python=3.13t pip
@@ -166,13 +190,32 @@ jobs:
     steps:
       - uses: actions/checkout@v5
       - name: Install the latest version of uv and set the python version
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           python-version: ${{ matrix.python-version }}
       - name: Test with python ${{ matrix.python-version }}
         run: uv run --frozen pytest
 ```
 
+### Python architecture
+
+Use `python-arch` to set `UV_PYTHON_ARCH` for the rest of the job. This selects the Python
+architecture independently of the version, including versions requested by `.python-version`.
+An explicit architecture or interpreter path in a Python request takes precedence.
+
+```yaml
+- uses: astral-sh/setup-uv@main
+  with:
+    python-version: "3.14"
+    python-arch: x86_64
+- run: uv run --frozen pytest
+```
+
+The input overrides an existing `UV_PYTHON_ARCH` value. When it is omitted, the action respects
+`UV_PYTHON_ARCH` from the environment. Both forms require a uv version that supports the variable;
+the action reports an error if the installed version does not support it. The selected architecture
+is included in the [cache key](docs/caching.md#cache-key).
+
 ### Working directory
 
 You can set the working directory with the `working-directory` input.
@@ -183,7 +226,7 @@ It also controls where [the venv gets created](#activate-environment), unless `v
 
 ```yaml
 - name: Install uv based on the config files in the working-directory
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     working-directory: my/subproject/dir
 ```
@@ -225,7 +268,7 @@ For example:
 - name: Checkout the repository
   uses: actions/checkout@main
 - name: Install the latest version of uv
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     enable-cache: true
 - name: Test
@@ -237,7 +280,7 @@ To install a specific version of Python, use
 
 ```yaml
 - name: Install the latest version of uv
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     enable-cache: true
 - name: Install Python 3.12
@@ -256,7 +299,7 @@ output:
   uses: actions/checkout@main
 - name: Install the default version of uv
   id: setup-uv
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
 - name: Print the installed version
   run: echo "Installed uv version is ${{ steps.setup-uv.outputs.uv-version }}"
 ```

__tests__/cache/restore-cache.test.ts

@@ -1,9 +1,20 @@
-import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  jest,
+} from "@jest/globals";
 import { createSetupInputs } from "../helpers/setup-inputs";
 
 const mockRestoreCache = jest.fn();
 const mockSaveState = jest.fn();
 const mockSetOutput = jest.fn();
+const mockGetArch = jest.fn(() => "x86_64");
+const mockGetOSNameVersion = jest.fn(() => "ubuntu-24.04");
+const mockGetPlatform = jest.fn(async () => "unknown-linux-gnu");
+const ORIGINAL_UV_PYTHON_ARCH = process.env.UV_PYTHON_ARCH;
 
 jest.unstable_mockModule("@actions/cache", () => ({
   restoreCache: mockRestoreCache,
@@ -24,9 +35,9 @@ jest.unstable_mockModule("../../src/utils/logging", () => ({
 }));
 
 jest.unstable_mockModule("../../src/utils/platforms", () => ({
-  getArch: jest.fn(() => "x86_64"),
-  getOSNameVersion: jest.fn(() => "ubuntu-24.04"),
-  getPlatform: jest.fn(async () => "unknown-linux-gnu"),
+  getArch: mockGetArch,
+  getOSNameVersion: mockGetOSNameVersion,
+  getPlatform: mockGetPlatform,
 }));
 
 const { restoreCache } = await import("../../src/cache/restore-cache");
@@ -38,7 +49,19 @@ function cacheKeyOutput(): string {
 }
 
 beforeEach(() => {
+  delete process.env.UV_PYTHON_ARCH;
   jest.clearAllMocks();
+  mockGetArch.mockReturnValue("x86_64");
+  mockGetOSNameVersion.mockReturnValue("ubuntu-24.04");
+  mockGetPlatform.mockResolvedValue("unknown-linux-gnu");
+});
+
+afterEach(() => {
+  if (ORIGINAL_UV_PYTHON_ARCH === undefined) {
+    delete process.env.UV_PYTHON_ARCH;
+  } else {
+    process.env.UV_PYTHON_ARCH = ORIGINAL_UV_PYTHON_ARCH;
+  }
 });
 
 describe("restoreCache", () => {
@@ -62,13 +85,48 @@ describe("restoreCache", () => {
     expect(cacheKey).toContain("-tests-3.10%2C3.11");
   });
 
-  it("keeps cache keys unchanged for exact Python versions and simple suffixes", async () => {
+  it("uses an unpruned cache key by default", async () => {
     const inputs = createSetupInputs({ cacheSuffix: "tests-3.11" });
 
     await restoreCache(inputs, "3.11");
 
     expect(cacheKeyOutput()).toBe(
-      "setup-uv-2-x86_64-unknown-linux-gnu-ubuntu-24.04-3.11-pruned-dependencyhash-tests-3.11",
+      "setup-uv-2-x86_64-unknown-linux-gnu-ubuntu-24.04-3.11-dependencyhash-tests-3.11",
     );
   });
+
+  it("includes an inherited Python architecture in the cache key", async () => {
+    process.env.UV_PYTHON_ARCH = "aarch64";
+
+    await restoreCache(createSetupInputs(), "3.14");
+
+    expect(cacheKeyOutput()).toContain("-3.14-python-aarch64-");
+  });
+
+  it.each(["aarch64", "x86_64"])(
+    "separates %s Python caches on a Windows ARM64 runner",
+    async (pythonArch) => {
+      mockGetArch.mockReturnValue("aarch64");
+      mockGetOSNameVersion.mockReturnValue("windows-11");
+      mockGetPlatform.mockResolvedValue("pc-windows-msvc");
+      const inputs = createSetupInputs({
+        cachePython: true,
+        pythonArch,
+        restoreCache: true,
+      });
+
+      await restoreCache(inputs, "3.14");
+
+      const cacheKey = `setup-uv-2-aarch64-pc-windows-msvc-windows-11-3.14-python-${pythonArch}-py-dependencyhash`;
+      expect(cacheKeyOutput()).toBe(cacheKey);
+      expect(mockRestoreCache).toHaveBeenCalledWith(
+        [inputs.cacheLocalPath?.path],
+        cacheKey,
+      );
+      expect(mockRestoreCache).toHaveBeenCalledWith(
+        [inputs.pythonDir],
+        `${cacheKey}-python`,
+      );
+    },
+  );
 });

__tests__/download/checksum/checksum.test.ts

@@ -26,9 +26,49 @@ test("provided checksum beats known checksums", async () => {
     "x86_64",
     "unknown-linux-gnu",
     "0.3.0",
+    "incorrect-manifest-checksum",
   );
 });
 
+test("known checksums beat manifest checksums", async () => {
+  await expect(
+    validateChecksum(
+      undefined,
+      filePath,
+      "x86_64",
+      "unknown-linux-gnu",
+      "0.3.0",
+      validChecksum,
+    ),
+  ).rejects.toThrow("did not match");
+});
+
+test("manifest checksums are used when no known checksum exists", async () => {
+  await expect(
+    validateChecksum(
+      undefined,
+      filePath,
+      "aarch64",
+      "pc-windows-msvc",
+      "1.2.3",
+      "incorrect-manifest-checksum",
+    ),
+  ).rejects.toThrow("did not match");
+});
+
+test("empty manifest checksums are rejected", async () => {
+  await expect(
+    validateChecksum(
+      undefined,
+      filePath,
+      "aarch64",
+      "pc-windows-msvc",
+      "1.2.3",
+      "",
+    ),
+  ).rejects.toThrow("No checksum found");
+});
+
 type KnownVersionFixture = { version: string; known: boolean };
 
 it.each<KnownVersionFixture>([
@@ -40,9 +80,9 @@ it.each<KnownVersionFixture>([
     known: false,
     version: "0.0.15",
   },
-])("isknownVersion should return $known for version $version", ({
-  version,
-  known,
-}) => {
+])(
+  "isknownVersion should return $known for version $version",
+  ({ version, known }) => {
     expect(isknownVersion(version)).toBe(known);
-});
+  },
+);

__tests__/download/checksum/known-version.test.ts

@@ -0,0 +1,20 @@
+import { expect, it, jest } from "@jest/globals";
+
+jest.unstable_mockModule(
+  "../../../src/download/checksum/known-checksums",
+  () => ({
+    KNOWN_CHECKSUMS: {
+      "aarch64-apple-darwin-1.9.0": "checksum",
+      "x86_64-unknown-linux-gnu-1.8.0": "checksum",
+      "x86_64-unknown-linux-gnu-1.10.0": "checksum",
+    },
+  }),
+);
+
+const { getLatestKnownVersion } = await import(
+  "../../../src/download/checksum/known-version"
+);
+
+it("returns the highest version with a built-in checksum", () => {
+  expect(getLatestKnownVersion()).toBe("1.10.0");
+});

__tests__/download/checksum/update-known-checksums.test.ts

@@ -0,0 +1,27 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { expect, test } from "@jest/globals";
+import { updateChecksums } from "../../../src/download/checksum/update-known-checksums";
+
+test("serializes checksum entries as JSON data", async () => {
+  const tempDirectory = await fs.mkdtemp(
+    path.join(os.tmpdir(), "setup-uv-checksums-test-"),
+  );
+  const outputPath = path.join(tempDirectory, "known-checksums.json");
+  const key = 'platform-1.0.0"\n};\nglobalThis.compromised = true;';
+  const checksum = 'checksum"\\\nvalue';
+
+  try {
+    await updateChecksums(outputPath, [
+      { checksum, key },
+      { checksum: "duplicate", key },
+    ]);
+
+    const content = await fs.readFile(outputPath, "utf8");
+    expect(JSON.parse(content)).toEqual({ [key]: checksum });
+    expect(content.endsWith("\n")).toBe(true);
+  } finally {
+    await fs.rm(tempDirectory, { force: true, recursive: true });
+  }
+});

__tests__/download/download-version.test.ts

@@ -1,5 +1,6 @@
 import { beforeEach, describe, expect, it, jest } from "@jest/globals";
 import * as semver from "semver";
+import { VERSIONS_MANIFEST_URL } from "../../src/utils/constants";
 
 const mockInfo = jest.fn();
 const mockWarning = jest.fn();
@@ -36,11 +37,14 @@ const mockGetLatestVersion = jest.fn<any>();
 // biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
 const mockGetAllVersions = jest.fn<any>();
 // biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
+const mockGetFirstMatchingVersion = jest.fn<any>();
+// biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
 const mockGetArtifact = jest.fn<any>();
 
 jest.unstable_mockModule("../../src/download/manifest", () => ({
   getAllVersions: mockGetAllVersions,
   getArtifact: mockGetArtifact,
+  getFirstMatchingVersion: mockGetFirstMatchingVersion,
   getLatestVersion: mockGetLatestVersion,
 }));
 
@@ -51,6 +55,12 @@ jest.unstable_mockModule("../../src/download/checksum/checksum", () => ({
   validateChecksum: mockValidateChecksum,
 }));
 
+const mockGetLatestKnownVersion = jest.fn(() => "0.9.25");
+
+jest.unstable_mockModule("../../src/download/checksum/known-version", () => ({
+  getLatestKnownVersion: mockGetLatestKnownVersion,
+}));
+
 const { downloadVersion, resolveVersion, rewriteToMirror } = await import(
   "../../src/download/download-version"
 );
@@ -65,8 +75,10 @@ describe("download-version", () => {
     mockCacheDir.mockReset();
     mockGetLatestVersion.mockReset();
     mockGetAllVersions.mockReset();
+    mockGetFirstMatchingVersion.mockReset();
     mockGetArtifact.mockReset();
     mockValidateChecksum.mockReset();
+    mockGetLatestKnownVersion.mockClear();
 
     mockDownloadTool.mockResolvedValue("/tmp/downloaded");
     mockExtractTar.mockResolvedValue("/tmp/extracted");
@@ -85,14 +97,53 @@ describe("download-version", () => {
       expect(mockGetLatestVersion).toHaveBeenCalledWith(undefined);
     });
 
-    it("uses the default manifest to resolve available versions", async () => {
-      mockGetAllVersions.mockResolvedValue(["0.9.26", "0.9.25"]);
+    it("resolves latest-known without reading the manifest", async () => {
+      const version = await resolveVersion("latest-known", undefined);
+
+      expect(version).toBe("0.9.25");
+      expect(mockGetLatestKnownVersion).toHaveBeenCalledTimes(1);
+      expect(mockGetLatestVersion).not.toHaveBeenCalled();
+      expect(mockGetAllVersions).not.toHaveBeenCalled();
+      expect(mockGetFirstMatchingVersion).not.toHaveBeenCalled();
+    });
+
+    it("stops at the first matching version in the default manifest", async () => {
+      mockGetFirstMatchingVersion.mockImplementation(
+        (predicate: (version: string) => boolean) =>
+          ["0.9.26", "0.9.25"].find(predicate),
+      );
 
       const version = await resolveVersion("^0.9.0", undefined);
 
       expect(version).toBe("0.9.26");
-      expect(mockGetAllVersions).toHaveBeenCalledTimes(1);
-      expect(mockGetAllVersions).toHaveBeenCalledWith(undefined);
+      expect(mockGetFirstMatchingVersion).toHaveBeenCalledTimes(1);
+      expect(mockGetAllVersions).not.toHaveBeenCalled();
+    });
+
+    it("streams ranges when the default manifest URL is explicit", async () => {
+      mockGetFirstMatchingVersion.mockImplementation(
+        (predicate: (version: string) => boolean) =>
+          ["0.9.26", "0.9.25"].find(predicate),
+      );
+
+      const version = await resolveVersion("^0.9.0", VERSIONS_MANIFEST_URL);
+
+      expect(version).toBe("0.9.26");
+      expect(mockGetFirstMatchingVersion).toHaveBeenCalledTimes(1);
+      expect(mockGetAllVersions).not.toHaveBeenCalled();
+    });
+
+    it("streams PEP 440 ranges from the default manifest", async () => {
+      mockGetFirstMatchingVersion.mockImplementation(
+        (predicate: (version: string) => boolean) =>
+          ["0.9.26", "0.9.25"].find(predicate),
+      );
+
+      const version = await resolveVersion("!=0.9.26", undefined);
+
+      expect(version).toBe("0.9.25");
+      expect(mockGetFirstMatchingVersion).toHaveBeenCalledTimes(1);
+      expect(mockGetAllVersions).not.toHaveBeenCalled();
     });
 
     it("treats == exact pins as explicit versions", async () => {
@@ -176,10 +227,10 @@ describe("download-version", () => {
       expect(mockValidateChecksum).not.toHaveBeenCalled();
     });
 
-    it("uses built-in checksums for default manifest downloads", async () => {
+    it("uses the default manifest checksum as a fallback", async () => {
       mockGetArtifact.mockResolvedValue({
         archiveFormat: "tar.gz",
-        checksum: "manifest-checksum-that-should-be-ignored",
+        checksum: "manifest-checksum",
         downloadUrl: "https://example.com/uv.tar.gz",
       });
 
@@ -197,6 +248,7 @@ describe("download-version", () => {
         "x86_64",
         "unknown-linux-gnu",
         "0.9.26",
+        "manifest-checksum",
       );
     });
 
@@ -349,6 +401,7 @@ describe("download-version", () => {
         "x86_64",
         "unknown-linux-gnu",
         "0.9.26",
+        "manifest-checksum",
       );
     });
 
@@ -374,6 +427,7 @@ describe("download-version", () => {
         "x86_64",
         "unknown-linux-gnu",
         "0.9.26",
+        "manifest-checksum",
       );
     });
 

__tests__/download/manifest.test.ts

@@ -1,4 +1,11 @@
-import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  jest,
+} from "@jest/globals";
 
 // biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
 const mockFetch = jest.fn<any>();
@@ -13,10 +20,12 @@ jest.unstable_mockModule("../../src/utils/fetch", () => ({
 }));
 
 const {
+  MANIFEST_FETCH_ATTEMPTS,
   clearManifestCache,
   fetchManifest,
   getAllVersions,
   getArtifact,
+  getFirstMatchingVersion,
   getLatestVersion,
   parseManifest,
 } = await import("../../src/download/manifest");
@@ -33,6 +42,7 @@ function createMockResponse(
   data: string,
 ) {
   return {
+    body: null,
     ok,
     status,
     statusText,
@@ -40,12 +50,41 @@ function createMockResponse(
   };
 }
 
+function createStreamingMockResponse(
+  chunks: string[],
+  cancel: () => void | Promise<void> = () => {},
+  close = false,
+) {
+  const encoder = new TextEncoder();
+  return {
+    body: new ReadableStream<Uint8Array>({
+      cancel,
+      start(controller) {
+        for (const chunk of chunks) {
+          controller.enqueue(encoder.encode(chunk));
+        }
+        if (close) {
+          controller.close();
+        }
+      },
+    }),
+    ok: true,
+    status: 200,
+    statusText: "OK",
+    text: async () => chunks.join(""),
+  };
+}
+
 describe("manifest", () => {
   beforeEach(() => {
     clearManifestCache();
     mockFetch.mockReset();
   });
 
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
   describe("fetchManifest", () => {
     it("fetches and parses manifest data", async () => {
       mockFetch.mockResolvedValue(
@@ -59,6 +98,34 @@ describe("manifest", () => {
       expect(versions[1]?.version).toBe("0.9.25");
     });
 
+    it("retries network failures", async () => {
+      jest.useFakeTimers();
+      mockFetch
+        .mockRejectedValueOnce(new Error("request timed out"))
+        .mockResolvedValueOnce(
+          createMockResponse(true, 200, "OK", sampleManifestResponse),
+        );
+
+      const result = fetchManifest();
+      await jest.runAllTimersAsync();
+
+      await expect(result).resolves.toHaveLength(2);
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it("stops after the configured number of network failures", async () => {
+      jest.useFakeTimers();
+      mockFetch.mockRejectedValue(new Error("request timed out"));
+
+      const result = expect(fetchManifest()).rejects.toThrow(
+        "request timed out",
+      );
+      await jest.runAllTimersAsync();
+
+      await result;
+      expect(mockFetch).toHaveBeenCalledTimes(MANIFEST_FETCH_ATTEMPTS);
+    });
+
     it("throws on a failed fetch", async () => {
       mockFetch.mockResolvedValue(
         createMockResponse(false, 500, "Internal Server Error", ""),
@@ -105,6 +172,75 @@ describe("manifest", () => {
         getLatestVersion("https://example.com/custom.ndjson"),
       ).resolves.toBe("0.9.26");
     });
+
+    it("stops reading the default manifest after the first record", async () => {
+      const [latestVersion] = sampleManifestResponse.split("\n");
+      const cancel = jest.fn();
+      mockFetch.mockResolvedValue(
+        createStreamingMockResponse(
+          [
+            latestVersion.slice(0, 100),
+            `${latestVersion.slice(100)}\n`,
+            "invalid trailing data\n",
+          ],
+          cancel,
+        ),
+      );
+
+      await expect(getLatestVersion()).resolves.toBe("0.9.26");
+      await expect(
+        getArtifact("0.9.26", "aarch64", "apple-darwin"),
+      ).resolves.toBeDefined();
+
+      expect(cancel).toHaveBeenCalledTimes(1);
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not fail when canceling the remaining response fails", async () => {
+      const [latestVersion] = sampleManifestResponse.split("\n");
+      mockFetch.mockResolvedValue(
+        createStreamingMockResponse([`${latestVersion}\n`], () =>
+          Promise.reject(new Error("cancel failed")),
+        ),
+      );
+
+      await expect(getLatestVersion()).resolves.toBe("0.9.26");
+    });
+  });
+
+  describe("getFirstMatchingVersion", () => {
+    it("stops at the first matching record", async () => {
+      const cancel = jest.fn();
+      mockFetch.mockResolvedValue(
+        createStreamingMockResponse(
+          [`${sampleManifestResponse}\n`, "invalid trailing data\n"],
+          cancel,
+        ),
+      );
+
+      await expect(
+        getFirstMatchingVersion((version) => version === "0.9.25"),
+      ).resolves.toBe("0.9.25");
+
+      expect(cancel).toHaveBeenCalledTimes(1);
+    });
+
+    it("caches a fully consumed response stream", async () => {
+      mockFetch.mockResolvedValue(
+        createStreamingMockResponse(
+          [`${sampleManifestResponse}\n`],
+          undefined,
+          true,
+        ),
+      );
+
+      await expect(
+        getFirstMatchingVersion((version) => version === "0.0.1"),
+      ).resolves.toBeUndefined();
+      await expect(getLatestVersion()).resolves.toBe("0.9.26");
+
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
   });
 
   describe("getArtifact", () => {
@@ -168,6 +304,60 @@ describe("manifest", () => {
 
       expect(artifact).toBeUndefined();
     });
+
+    it("does not cache records from a failed stream read", async () => {
+      const [latestVersion] = sampleManifestResponse.split("\n");
+      mockFetch
+        .mockResolvedValueOnce(
+          createStreamingMockResponse([
+            `${latestVersion}\n`,
+            "invalid manifest record\n",
+          ]),
+        )
+        .mockResolvedValueOnce(
+          createMockResponse(true, 200, "OK", sampleManifestResponse),
+        );
+
+      await expect(
+        getArtifact("0.0.1", "aarch64", "apple-darwin"),
+      ).rejects.toThrow("Failed to parse manifest data");
+      await expect(getLatestVersion()).resolves.toBe("0.9.26");
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it("does not cache records when the response stream fails", async () => {
+      const [latestVersion] = sampleManifestResponse.split("\n");
+      const encoder = new TextEncoder();
+      let sentVersion = false;
+      const body = new ReadableStream<Uint8Array>({
+        pull(controller) {
+          if (!sentVersion) {
+            sentVersion = true;
+            controller.enqueue(encoder.encode(`${latestVersion}\n`));
+            return;
+          }
+          controller.error(new Error("response stream failed"));
+        },
+      });
+      mockFetch
+        .mockResolvedValueOnce({
+          body,
+          ok: true,
+          status: 200,
+          statusText: "OK",
+        })
+        .mockResolvedValueOnce(
+          createMockResponse(true, 200, "OK", sampleManifestResponse),
+        );
+
+      await expect(
+        getArtifact("0.0.1", "aarch64", "apple-darwin"),
+      ).rejects.toThrow("response stream failed");
+      await expect(getLatestVersion()).resolves.toBe("0.9.26");
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
   });
 
   describe("parseManifest", () => {

__tests__/fixtures/.tool-versions

@@ -1 +1,2 @@
 uv 0.5.15
+python 3.13.1t

__tests__/helpers/setup-inputs.ts

@@ -20,7 +20,8 @@ export function createSetupInputs(
     ignoreEmptyWorkdir: false,
     ignoreNothingToCache: false,
     noProject: false,
-    pruneCache: true,
+    pruneCache: false,
+    pythonArch: "",
     pythonDir: "/tmp/uv-python-dir",
     pythonVersion: "",
     quiet: false,

__tests__/utils/inputs.test.ts

@@ -12,10 +12,14 @@ import {
 
 let mockInputs: Record<string, string> = {};
 const tempDirs: string[] = [];
+const ORIGINAL_GITHUB_EVENT_NAME = process.env.GITHUB_EVENT_NAME;
+const ORIGINAL_GITHUB_REF = process.env.GITHUB_REF;
 const ORIGINAL_HOME = process.env.HOME;
 const ORIGINAL_RUNNER_ENVIRONMENT = process.env.RUNNER_ENVIRONMENT;
 const ORIGINAL_RUNNER_TEMP = process.env.RUNNER_TEMP;
 const ORIGINAL_UV_CACHE_DIR = process.env.UV_CACHE_DIR;
+const ORIGINAL_UV_PYTHON = process.env.UV_PYTHON;
+const ORIGINAL_UV_PYTHON_ARCH = process.env.UV_PYTHON_ARCH;
 const ORIGINAL_UV_PYTHON_INSTALL_DIR = process.env.UV_PYTHON_INSTALL_DIR;
 
 const mockDebug = jest.fn();
@@ -34,7 +38,9 @@ jest.unstable_mockModule("@actions/core", () => ({
   warning: mockWarning,
 }));
 
-const { CacheLocalSource, loadInputs } = await import("../../src/utils/inputs");
+const { CacheLocalSource, loadInputs, resolvePythonArch } = await import(
+  "../../src/utils/inputs"
+);
 
 function createTempProject(files: Record<string, string> = {}): string {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "setup-uv-inputs-test-"));
@@ -52,10 +58,14 @@ function createTempProject(files: Record<string, string> = {}): string {
 function resetEnvironment(): void {
   jest.clearAllMocks();
   mockInputs = {};
+  delete process.env.GITHUB_EVENT_NAME;
+  delete process.env.GITHUB_REF;
   process.env.HOME = "/home/testuser";
   delete process.env.RUNNER_ENVIRONMENT;
   delete process.env.RUNNER_TEMP;
   delete process.env.UV_CACHE_DIR;
+  delete process.env.UV_PYTHON;
+  delete process.env.UV_PYTHON_ARCH;
   delete process.env.UV_PYTHON_INSTALL_DIR;
 }
 
@@ -64,10 +74,18 @@ function restoreEnvironment(): void {
     fs.rmSync(dir, { force: true, recursive: true });
   }
 
+  process.env.GITHUB_EVENT_NAME = ORIGINAL_GITHUB_EVENT_NAME;
+  process.env.GITHUB_REF = ORIGINAL_GITHUB_REF;
   process.env.HOME = ORIGINAL_HOME;
   process.env.RUNNER_ENVIRONMENT = ORIGINAL_RUNNER_ENVIRONMENT;
   process.env.RUNNER_TEMP = ORIGINAL_RUNNER_TEMP;
   process.env.UV_CACHE_DIR = ORIGINAL_UV_CACHE_DIR;
+  process.env.UV_PYTHON = ORIGINAL_UV_PYTHON;
+  if (ORIGINAL_UV_PYTHON_ARCH === undefined) {
+    delete process.env.UV_PYTHON_ARCH;
+  } else {
+    process.env.UV_PYTHON_ARCH = ORIGINAL_UV_PYTHON_ARCH;
+  }
   process.env.UV_PYTHON_INSTALL_DIR = ORIGINAL_UV_PYTHON_INSTALL_DIR;
 }
 
@@ -89,11 +107,182 @@ describe("loadInputs", () => {
       source: CacheLocalSource.Default,
     });
     expect(inputs.pythonDir).toBe("/runner-temp/uv-python-dir");
+    expect(inputs.pythonArch).toBe("");
     expect(inputs.venvPath).toBe("/workspace/.venv");
     expect(inputs.manifestFile).toBeUndefined();
     expect(inputs.resolutionStrategy).toBe("highest");
   });
 
+  it("uses the Python version from an explicitly selected .tool-versions file", () => {
+    mockInputs["working-directory"] = createTempProject({
+      ".tool-versions": "uv 0.12.3\npython 3.13.1t\n",
+    });
+    mockInputs["version-file"] = ".tool-versions";
+
+    const inputs = loadInputs();
+
+    expect(inputs.pythonVersion).toBe("3.13.1t");
+  });
+
+  it("prefers the python-version input over .tool-versions", () => {
+    mockInputs["working-directory"] = createTempProject({
+      ".tool-versions": "uv 0.12.3\npython 3.13\n",
+    });
+    mockInputs["version-file"] = ".tool-versions";
+    mockInputs["python-version"] = "3.12";
+
+    const inputs = loadInputs();
+
+    expect(inputs.pythonVersion).toBe("3.12");
+  });
+
+  it("preserves UV_PYTHON instead of overriding it from .tool-versions", () => {
+    mockInputs["working-directory"] = createTempProject({
+      ".tool-versions": "uv 0.12.3\npython 3.13\n",
+    });
+    mockInputs["version-file"] = ".tool-versions";
+    process.env.UV_PYTHON = "3.11";
+
+    const inputs = loadInputs();
+
+    expect(inputs.pythonVersion).toBe("");
+    expect(process.env.UV_PYTHON).toBe("3.11");
+  });
+
+  it("does not discover .tool-versions from the working directory", () => {
+    mockInputs["working-directory"] = createTempProject({
+      ".tool-versions": "uv 0.12.3\npython 3.13\n",
+    });
+
+    const inputs = loadInputs();
+
+    expect(inputs.pythonVersion).toBe("");
+  });
+
+  it("prefers the python-arch input over UV_PYTHON_ARCH", () => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["python-arch"] = "x86_64";
+    process.env.UV_PYTHON_ARCH = "aarch64";
+
+    const inputs = loadInputs();
+    expect(inputs.pythonArch).toBe("x86_64");
+    expect(resolvePythonArch(inputs.pythonArch)).toBe("x86_64");
+  });
+
+  it.each(["aarch64", "x86_64_v3", ""])(
+    "uses UV_PYTHON_ARCH when python-arch is omitted: %s",
+    (pythonArch) => {
+      mockInputs["working-directory"] = "/workspace";
+      process.env.UV_PYTHON_ARCH = pythonArch;
+
+      const inputs = loadInputs();
+      expect(inputs.pythonArch).toBe("");
+      expect(resolvePythonArch(inputs.pythonArch)).toBe(pythonArch);
+    },
+  );
+
+  it.each(["pull_request_target", "workflow_run", "release"])(
+    "disables automatic caching for the %s event",
+    (eventName) => {
+      mockInputs["working-directory"] = "/workspace";
+      mockInputs["enable-cache"] = "auto";
+      process.env.RUNNER_ENVIRONMENT = "github-hosted";
+      process.env.RUNNER_TEMP = "/runner-temp";
+      process.env.GITHUB_EVENT_NAME = eventName;
+
+      const inputs = loadInputs();
+
+      expect(inputs.enableCache).toBe(false);
+      expect(mockInfo).toHaveBeenCalledWith(
+        `Caching is disabled for the ${eventName} event`,
+      );
+    },
+  );
+
+  it("disables automatic caching for tag pushes", () => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["enable-cache"] = "auto";
+    process.env.RUNNER_ENVIRONMENT = "github-hosted";
+    process.env.RUNNER_TEMP = "/runner-temp";
+    process.env.GITHUB_EVENT_NAME = "push";
+    process.env.GITHUB_REF = "refs/tags/v1.0.0";
+
+    const inputs = loadInputs();
+
+    expect(inputs.enableCache).toBe(false);
+    expect(mockInfo).toHaveBeenCalledWith("Caching is disabled for tag pushes");
+  });
+
+  it("enables automatic caching for branch pushes", () => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["enable-cache"] = "auto";
+    process.env.RUNNER_ENVIRONMENT = "github-hosted";
+    process.env.RUNNER_TEMP = "/runner-temp";
+    process.env.GITHUB_EVENT_NAME = "push";
+    process.env.GITHUB_REF = "refs/heads/main";
+
+    const inputs = loadInputs();
+
+    expect(inputs.enableCache).toBe(true);
+  });
+
+  it("honors explicitly enabled caching for sensitive events", () => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["enable-cache"] = "true";
+    process.env.RUNNER_ENVIRONMENT = "github-hosted";
+    process.env.RUNNER_TEMP = "/runner-temp";
+    process.env.GITHUB_EVENT_NAME = "release";
+
+    const inputs = loadInputs();
+
+    expect(inputs.enableCache).toBe(true);
+  });
+
+  it("restores but does not save cache automatically for merge groups", () => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["enable-cache"] = "auto";
+    mockInputs["restore-cache"] = "true";
+    mockInputs["save-cache"] = "auto";
+    process.env.RUNNER_ENVIRONMENT = "github-hosted";
+    process.env.RUNNER_TEMP = "/runner-temp";
+    process.env.GITHUB_EVENT_NAME = "merge_group";
+
+    const inputs = loadInputs();
+
+    expect(inputs.enableCache).toBe(true);
+    expect(inputs.restoreCache).toBe(true);
+    expect(inputs.saveCache).toBe(false);
+    expect(mockInfo).toHaveBeenCalledWith(
+      "Cache saving is disabled for the merge_group event",
+    );
+  });
+
+  it.each([
+    ["true", true],
+    ["false", false],
+  ])("honors save-cache %s for merge groups", (saveCacheInput, expected) => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["save-cache"] = saveCacheInput;
+    process.env.GITHUB_EVENT_NAME = "merge_group";
+
+    const inputs = loadInputs();
+
+    expect(inputs.saveCache).toBe(expected);
+    expect(mockInfo).not.toHaveBeenCalledWith(
+      "Cache saving is disabled for the merge_group event",
+    );
+  });
+
+  it("automatically saves cache for other events", () => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["save-cache"] = "auto";
+    process.env.GITHUB_EVENT_NAME = "push";
+
+    const inputs = loadInputs();
+
+    expect(inputs.saveCache).toBe(true);
+  });
+
   it("uses cache-dir from pyproject.toml when present", () => {
     mockInputs["working-directory"] = createTempProject({
       "pyproject.toml": `[project]

__tests__/utils/python-arch.test.ts

@@ -0,0 +1,152 @@
+import { promisify } from "node:util";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  jest,
+} from "@jest/globals";
+
+const ORIGINAL_UV_PYTHON_ARCH = process.env.UV_PYTHON_ARCH;
+
+const mockExecFile =
+  jest.fn<
+    (...args: unknown[]) => Promise<{
+      stdout: string;
+      stderr: string;
+    }>
+  >();
+const mockExportVariable = jest.fn();
+
+jest.unstable_mockModule("node:child_process", () => ({
+  execFile: Object.assign(mockExecFile, { [promisify.custom]: mockExecFile }),
+}));
+jest.unstable_mockModule("@actions/core", () => ({
+  exportVariable: mockExportVariable,
+}));
+jest.unstable_mockModule("../../src/utils/logging", () => ({
+  info: jest.fn(),
+}));
+
+const { setupPythonArch } = await import("../../src/utils/python-arch");
+
+const supportedProbe = Object.assign(new Error("uv exited with code 2"), {
+  code: 2,
+  stderr:
+    "error: Failed to parse environment variable `UV_PYTHON_ARCH` with invalid value `setup-uv-probe`: Unknown architecture: setup-uv-probe\n",
+});
+const success = { stderr: "", stdout: "/cache\n" };
+
+beforeEach(() => {
+  delete process.env.UV_PYTHON_ARCH;
+  jest.clearAllMocks();
+  mockExecFile
+    .mockReset()
+    .mockRejectedValueOnce(supportedProbe)
+    .mockResolvedValueOnce(success);
+});
+
+afterEach(() => {
+  if (ORIGINAL_UV_PYTHON_ARCH === undefined) {
+    delete process.env.UV_PYTHON_ARCH;
+  } else {
+    process.env.UV_PYTHON_ARCH = ORIGINAL_UV_PYTHON_ARCH;
+  }
+});
+
+describe("setupPythonArch", () => {
+  it("leaves Python selection alone without an architecture", async () => {
+    await setupPythonArch("/tools/uv", "");
+
+    expect(mockExecFile).not.toHaveBeenCalled();
+    expect(mockExportVariable).not.toHaveBeenCalled();
+  });
+
+  it("validates an inherited architecture without exporting it", async () => {
+    process.env.UV_PYTHON_ARCH = "aarch64";
+
+    await setupPythonArch("/tools/uv", "");
+
+    expect(mockExecFile).toHaveBeenNthCalledWith(
+      2,
+      "/tools/uv",
+      ["--no-config", "cache", "dir"],
+      expect.objectContaining({
+        env: expect.objectContaining({ UV_PYTHON_ARCH: "aarch64" }),
+      }),
+    );
+    expect(mockExportVariable).not.toHaveBeenCalled();
+    expect(process.env.UV_PYTHON_ARCH).toBe("aarch64");
+  });
+
+  it.each(["/runner temp/uv", "C:\\runner temp\\uv.exe"])(
+    "validates and exports the architecture using the installed uv: %s",
+    async (uvPath) => {
+      await setupPythonArch(uvPath, "x86_64");
+
+      expect(mockExecFile).toHaveBeenNthCalledWith(
+        1,
+        uvPath,
+        ["--no-config", "cache", "dir"],
+        expect.objectContaining({
+          encoding: "utf8",
+          env: expect.objectContaining({ UV_PYTHON_ARCH: "setup-uv-probe" }),
+        }),
+      );
+      expect(mockExecFile).toHaveBeenNthCalledWith(
+        2,
+        uvPath,
+        ["--no-config", "cache", "dir"],
+        expect.objectContaining({
+          env: expect.objectContaining({ UV_PYTHON_ARCH: "x86_64" }),
+        }),
+      );
+      expect(mockExportVariable).toHaveBeenCalledWith(
+        "UV_PYTHON_ARCH",
+        "x86_64",
+      );
+    },
+  );
+
+  it("rejects uv versions that ignore UV_PYTHON_ARCH", async () => {
+    mockExecFile.mockReset().mockResolvedValue(success);
+
+    await expect(setupPythonArch("/tools/uv", "x86_64")).rejects.toThrow(
+      "The installed version of uv does not support UV_PYTHON_ARCH",
+    );
+    expect(mockExecFile).toHaveBeenCalledTimes(1);
+    expect(mockExportVariable).not.toHaveBeenCalled();
+  });
+
+  it("reports unexpected probe failures", async () => {
+    mockExecFile.mockReset().mockRejectedValue(
+      Object.assign(new Error("uv exited with code 2"), {
+        code: 2,
+        stderr: "error: unrelated configuration error\n",
+      }),
+    );
+
+    await expect(setupPythonArch("/tools/uv", "x86_64")).rejects.toThrow(
+      "Failed to check uv's support for UV_PYTHON_ARCH: error: unrelated configuration error",
+    );
+    expect(mockExportVariable).not.toHaveBeenCalled();
+  });
+
+  it("reports invalid architectures before exporting them", async () => {
+    mockExecFile
+      .mockReset()
+      .mockRejectedValueOnce(supportedProbe)
+      .mockRejectedValueOnce(
+        Object.assign(new Error("uv exited with code 2"), {
+          code: 2,
+          stderr: "error: Unknown architecture: invalid\n",
+        }),
+      );
+
+    await expect(setupPythonArch("/tools/uv", "invalid")).rejects.toThrow(
+      "Failed to set Python architecture to invalid: error: Unknown architecture: invalid",
+    );
+    expect(mockExportVariable).not.toHaveBeenCalled();
+  });
+});

__tests__/utils/python-runtime.test.ts

@@ -0,0 +1,86 @@
+import { promisify } from "node:util";
+import { beforeEach, expect, it, jest } from "@jest/globals";
+import { createSetupInputs } from "../helpers/setup-inputs";
+
+const mockExecFile =
+  jest.fn<
+    (...args: unknown[]) => Promise<{ stdout: string; stderr: string }>
+  >();
+const inputs = createSetupInputs({
+  activateEnvironment: true,
+  pythonVersion: "3.15t",
+});
+
+jest.unstable_mockModule("node:child_process", () => ({
+  // execFile's custom promisifier returns both stdout and stderr.
+  execFile: Object.assign(mockExecFile, { [promisify.custom]: mockExecFile }),
+}));
+
+const { getPythonRuntimeId } = await import("../../src/utils/python-runtime");
+
+beforeEach(() => {
+  mockExecFile.mockReset();
+  mockExecFile.mockResolvedValue({
+    stderr: "",
+    stdout: '[{"key":"cpython-3.13.1-linux-x86_64-gnu"}]\r\n',
+  });
+});
+
+it("does not query uv without environment activation", async () => {
+  expect(
+    await getPythonRuntimeId({ ...inputs, activateEnvironment: false }),
+  ).toBe("");
+  expect(mockExecFile).not.toHaveBeenCalled();
+});
+
+it.each([
+  "cpython-3.13.1-linux-x86_64-gnu",
+  "cpython-3.15.0rc1+freethreaded-macos-aarch64-none",
+  "cpython-3.15.0rc2+freethreaded-windows-x86_64-none",
+  "pypy-3.11.15-linux-x86_64-gnu",
+])("returns uv's opaque runtime key unchanged: %s", async (key) => {
+  mockExecFile.mockResolvedValue({
+    stderr: "",
+    stdout: `${JSON.stringify([{ key }])}\r\n`,
+  });
+  expect(await getPythonRuntimeId(inputs)).toBe(key);
+});
+
+it.each(['/runner temp/a "quoted" venv', "C:\\runner temp\\custom venv"])(
+  "queries the exact venv directory: %s",
+  async (venvPath) => {
+    await getPythonRuntimeId({ ...inputs, venvPath });
+    expect(mockExecFile).toHaveBeenCalledWith(
+      "uv",
+      [
+        "python",
+        "list",
+        venvPath,
+        "--only-installed",
+        "--output-format",
+        "json",
+      ],
+      { encoding: "utf8" },
+    );
+  },
+);
+
+it.each([
+  new Error("uv failed"),
+  "not JSON",
+  "null",
+  "{}",
+  "[]",
+  '[{"key":""}]',
+  '[{"key":123}]',
+  '[{"key":"first"},{"key":"second"}]',
+])("rejects uv failure or invalid results: %s", async (result) => {
+  if (result instanceof Error) {
+    mockExecFile.mockRejectedValue(result);
+  } else {
+    mockExecFile.mockResolvedValue({ stderr: "", stdout: result });
+  }
+  await expect(getPythonRuntimeId(inputs)).rejects.toThrow(
+    "Failed to identify the activated environment's Python runtime:",
+  );
+});

__tests__/version/requirements-file.test.ts

@@ -15,7 +15,9 @@ test("ignores dependencies starting with uv", async () => {
 test.each([
   ["without space before marker", "uv==0.11.20; sys_platform != 'emscripten'"],
   ["with space before marker", "uv==0.11.20 ; sys_platform != 'emscripten'"],
-])("strips PEP 508 markers from pyproject dependency groups %s", (_, dependency) => {
+])(
+  "strips PEP 508 markers from pyproject dependency groups %s",
+  (_, dependency) => {
     const parsedVersion = getUvVersionFromPyprojectContent(`[dependency-groups]
 test = [
   "${dependency}",
@@ -23,7 +25,8 @@ test = [
 `);
 
     expect(parsedVersion).toBe("==0.11.20");
-});
+  },
+);
 
 test("strips PEP 508 markers from requirements dependencies", () => {
   const parsedVersion = getUvVersionFromRequirementsText(

__tests__/version/tool-versions-file.test.ts

@@ -21,6 +21,11 @@ async function getVersionFromToolVersions(filePath: string) {
   return getUvVersionFromToolVersions(filePath);
 }
 
+async function getPythonVersionFromToolVersions(filePath: string) {
+  const module = await import("../../src/version/tool-versions-file");
+  return module.getPythonVersionFromToolVersions(filePath);
+}
+
 describe("getUvVersionFromToolVersions", () => {
   beforeEach(() => {
     jest.resetModules();
@@ -61,8 +66,8 @@ describe("getUvVersionFromToolVersions", () => {
     expect(result).toBe("0.3.0");
   });
 
-  it("should skip commented lines", async () => {
-    const fileContent = "# uv 0.1.0\npython 3.11.0\nuv 0.2.0";
+  it("should skip comments", async () => {
+    const fileContent = "# uv 0.1.0\npython 3.11.0\nuv 0.2.0 # inline comment";
     mockReadFileSync.mockReturnValue(fileContent);
 
     const result = await getVersionFromToolVersions(".tool-versions");
@@ -108,6 +113,20 @@ describe("getUvVersionFromToolVersions", () => {
     );
   });
 
+  it.each(["/my/python/exploit", "my/exploited/uv", "C:\\exploited\\uv"])(
+    "should warn and return undefined for path %s",
+    async (version) => {
+      mockReadFileSync.mockReturnValue(`uv ${version}`);
+
+      const result = await getVersionFromToolVersions(".tool-versions");
+
+      expect(result).toBeUndefined();
+      expect(mockWarning).toHaveBeenCalledWith(
+        `The uv version ${version} in .tool-versions is not supported. Paths are not allowed.`,
+      );
+    },
+  );
+
   it("should handle file path with .tool-versions extension", async () => {
     const fileContent = "uv 0.1.0";
     mockReadFileSync.mockReturnValue(fileContent);
@@ -121,3 +140,72 @@ describe("getUvVersionFromToolVersions", () => {
     );
   });
 });
+
+describe("getPythonVersionFromToolVersions", () => {
+  beforeEach(() => {
+    jest.resetModules();
+    jest.clearAllMocks();
+  });
+
+  it("should return version for a valid Python entry", async () => {
+    mockReadFileSync.mockReturnValue(
+      "nodejs 24.0.0\r\npython v3.13.1t # use free-threaded Python\r\nuv 0.12.3",
+    );
+
+    const result = await getPythonVersionFromToolVersions(".tool-versions");
+
+    expect(result).toBe("3.13.1t");
+  });
+
+  it("should return the first matching Python version", async () => {
+    mockReadFileSync.mockReturnValue("python 3.12\npython 3.13");
+
+    const result = await getPythonVersionFromToolVersions(".tool-versions");
+
+    expect(result).toBe("3.12");
+  });
+
+  it("should return undefined when no Python entry is found", async () => {
+    mockReadFileSync.mockReturnValue("uv 0.12.3\nnodejs 24.0.0");
+
+    const result = await getPythonVersionFromToolVersions(".tool-versions");
+
+    expect(result).toBeUndefined();
+  });
+
+  it("should warn and return undefined for multiple Python versions", async () => {
+    mockReadFileSync.mockReturnValue("python 3.13 3.12 system");
+
+    const result = await getPythonVersionFromToolVersions(".tool-versions");
+
+    expect(result).toBeUndefined();
+    expect(mockWarning).toHaveBeenCalledWith(
+      "Multiple Python versions in .tool-versions are not supported. The Python entry will be ignored.",
+    );
+  });
+
+  it.each([
+    "ref:main",
+    "path:~/src/python",
+    "system",
+    "/my/python/exploit",
+    "my/exploited/python",
+    "C:\\exploited\\python",
+  ])("should warn and return undefined for %s", async (version) => {
+    mockReadFileSync.mockReturnValue(`python ${version}`);
+
+    const result = await getPythonVersionFromToolVersions(".tool-versions");
+
+    expect(result).toBeUndefined();
+    expect(mockWarning).toHaveBeenCalledWith(
+      `The Python version ${version} in .tool-versions is not supported. The Python entry will be ignored.`,
+    );
+  });
+
+  it("should return undefined for non-.tool-versions files", async () => {
+    const result = await getPythonVersionFromToolVersions(".python-version");
+
+    expect(result).toBeUndefined();
+    expect(mockReadFileSync).not.toHaveBeenCalled();
+  });
+});

__tests__/workflows/workflow-run.yml

@@ -0,0 +1,42 @@
+name: "test workflow_run caching"
+
+on: # zizmor: ignore[dangerous-triggers] this workflow is a test fixture executed by act only
+  workflow_run:
+    workflows:
+      - test
+    types:
+      - completed
+
+permissions:
+  contents: read
+
+jobs:
+  test-cache-disabled:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Setup uv with automatic caching
+        id: setup-uv
+        uses: ./
+      - name: Verify automatic caching is disabled
+        env:
+          CACHE_KEY: ${{ steps.setup-uv.outputs.cache-key }}
+        run: |
+          if [ "$GITHUB_EVENT_NAME" != "workflow_run" ]; then
+            echo "Expected workflow_run event, got: $GITHUB_EVENT_NAME"
+            exit 1
+          fi
+          if [ "$RUNNER_ENVIRONMENT" != "github-hosted" ]; then
+            echo "Expected a simulated GitHub-hosted runner, got: $RUNNER_ENVIRONMENT"
+            exit 1
+          fi
+          if [ -n "$CACHE_KEY" ]; then
+            echo "Cache key should not be set for a workflow_run event: $CACHE_KEY"
+            exit 1
+          fi
+          if [ -n "$UV_CACHE_DIR" ]; then
+            echo "UV_CACHE_DIR should not be set for a workflow_run event: $UV_CACHE_DIR"
+            exit 1
+          fi

action-types.yml

@@ -7,6 +7,8 @@ inputs:
     type: string
   python-version:
     type: string
+  python-arch:
+    type: string
   activate-environment:
     type: boolean
   venv-path:
@@ -33,7 +35,11 @@ inputs:
   restore-cache:
     type: boolean
   save-cache:
-    type: boolean
+    type: enum
+    allowed-values:
+      - "true"
+      - "false"
+      - auto
   cache-suffix:
     type: string
   cache-local-path:
@@ -79,5 +85,7 @@ outputs:
     type: string
   python-version:
     type: string
+  python-runtime-id:
+    type: string
   python-cache-hit:
     type: boolean

action.yml

@@ -4,13 +4,16 @@ description:
 author: "astral-sh"
 inputs:
   version:
-    description: "The version of uv to install e.g., `0.5.0` Defaults to the version in pyproject.toml or 'latest'."
+    description: "The version of uv to install, e.g., `0.5.0`, `latest`, or `latest-known`. Defaults to the version in pyproject.toml or `latest`."
     default: ""
   version-file:
-    description: "Path to a file containing the version of uv to install, e.g., uv.toml, pyproject.toml, .tool-versions, requirements.txt or uv.lock. Defaults to searching for uv.toml and if not found pyproject.toml."
+    description: "Path to a file containing the version of uv to install, e.g., uv.toml, pyproject.toml, .tool-versions, requirements.txt or uv.lock. A selected .tool-versions file can also provide the Python version. Defaults to searching for uv.toml and if not found pyproject.toml."
     default: ""
   python-version:
-    description: "The version of Python to set UV_PYTHON to"
+    description: "The version of Python to set UV_PYTHON to. Overrides the Python version from .tool-versions."
+    required: false
+  python-arch:
+    description: "The Python architecture to set UV_PYTHON_ARCH to, e.g., x86_64 or aarch64. Overrides UV_PYTHON_ARCH."
     required: false
   activate-environment:
     description: "Use uv venv to activate a venv ready to be used by later steps. "
@@ -33,7 +36,7 @@ inputs:
     required: false
     default: ${{ github.token }}
   enable-cache:
-    description: "Enable uploading of the uv cache"
+    description: "Enable the GitHub Actions cache for uv. 'auto' enables caching on GitHub-hosted runners except for release, tag push, pull_request_target, and workflow_run events."
     default: "auto"
   cache-dependency-glob:
     description:
@@ -51,8 +54,8 @@ inputs:
     description: "Whether to restore the cache if found."
     default: "true"
   save-cache:
-    description: "Whether to save the cache after the run."
-    default: "true"
+    description: "Whether to save the cache after the run. 'auto' disables saving for merge_group events."
+    default: "auto"
   cache-suffix:
     description: "Suffix for the cache key"
     required: false
@@ -61,7 +64,7 @@ inputs:
     default: ""
   prune-cache:
     description: "Prune cache before saving."
-    default: "true"
+    default: "false"
   cache-python:
     description: "Upload managed Python installations to the Github Actions cache."
     default: "false"
@@ -107,6 +110,8 @@ outputs:
     description: "Path to the activated venv if activate-environment is true"
   python-version:
     description: "The Python version that was set."
+  python-runtime-id:
+    description: "An opaque identifier reported by uv for the activated venv's Python runtime. Empty when activate-environment is false."
   python-cache-hit:
     description: "A boolean value to indicate the Python cache entry was found"
 runs:

biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.16/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.9/schema.json",
   "assist": {
     "actions": {
       "source": {
@@ -34,7 +34,7 @@
   "linter": {
     "enabled": true,
     "rules": {
-      "recommended": true
+      "preset": "recommended"
     }
   },
   "vcs": {

docs/advanced-version-configuration.md

@@ -6,16 +6,29 @@ This document covers advanced options for configuring which version of uv to ins
 
 ```yaml
 - name: Install the latest version of uv
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     version: "latest"
 ```
 
+## Install the latest version with a checksum verified by this action
+
+Use `latest-known` to install the newest uv version whose checksums were bundled with the version of setup-uv used by your workflow. Version resolution is performed locally without fetching the latest release, so updating setup-uv also updates the version selected by `latest-known`.
+
+When `manifest-file` is set, `latest-known` still selects a version from setup-uv's bundled checksum table, but the artifact and checksum come from the custom manifest.
+
+```yaml
+- name: Install the latest version of uv known to setup-uv
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    version: "latest-known"
+```
+
 ## Install a specific version
 
 ```yaml
 - name: Install a specific version of uv
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     version: "0.4.4"
 ```
@@ -28,21 +41,21 @@ to install the latest version that satisfies the range.
 
 ```yaml
 - name: Install a semver range of uv
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     version: ">=0.4.0"
 ```
 
 ```yaml
 - name: Pinning a minor version of uv
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     version: "0.4.x"
 ```
 
 ```yaml
 - name: Install a pep440-specifier-satisfying version of uv
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     version: ">=0.4.25,<0.5"
 ```
@@ -54,7 +67,7 @@ You can change this behavior using the `resolution-strategy` input:
 
 ```yaml
 - name: Install the lowest compatible version of uv
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     version: ">=0.4.0"
     resolution-strategy: "lowest"
@@ -72,11 +85,14 @@ You can use the `version-file` input to specify a file that contains the version
 This can either be a `pyproject.toml` or `uv.toml` file which defines a `required-version` or
 uv defined as a dependency in `pyproject.toml` or `requirements.txt`.
 
-[asdf](https://asdf-vm.com/) `.tool-versions` is also supported, but without the `ref` syntax.
+[asdf](https://asdf-vm.com/) `.tool-versions` is also supported for selecting uv. If neither
+`python-version` nor `UV_PYTHON` is set, the `python` entry from the selected file is also exported
+as `UV_PYTHON`. Only a single Python version is supported; multiple fallback versions and the asdf
+`ref:`, `path:`, and `system` forms are ignored with a warning.
 
 ```yaml
 - name: Install uv based on the version defined in pyproject.toml
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     version-file: "pyproject.toml"
 ```
@@ -87,7 +103,7 @@ silently picking up a newer uv until the lockfile is updated.
 
 ```yaml
 - name: Install uv based on the version locked in uv.lock
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     version-file: "uv.lock"
 ```

docs/caching.md

@@ -11,6 +11,7 @@ The cache key is automatically generated based on:
   `pc-windows-msvc`)
 - **OS version**: OS name and version (e.g., `ubuntu-22.04`, `macos-14`, `windows-2022`)
 - **Python version**: The Python version in use
+- **Python architecture**: The architecture selected by `python-arch` or `UV_PYTHON_ARCH`, when set
 - **Cache options**: Whether pruning and Python caching are enabled
 - **Dependency hash**: Hash of files matching `cache-dependency-glob`
 - **Suffix**: Optional `cache-suffix` if provided
@@ -23,7 +24,7 @@ The computed cache key is available as the `cache-key` output:
 ```yaml
 - name: Setup uv
   id: setup-uv
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     enable-cache: true
 - name: Print cache key
@@ -33,12 +34,15 @@ The computed cache key is available as the `cache-key` output:
 ## Enable caching
 
 > [!NOTE]
-> The cache is pruned before it is uploaded to the GitHub Actions cache. This can lead to
-> a small or empty cache. See [Disable cache pruning](#disable-cache-pruning) for more details.
+> The entire uv cache is uploaded to the GitHub Actions cache by default. To reduce the cache size,
+> see [Enable cache pruning](#enable-cache-pruning).
 
 If you enable caching, the [uv cache](https://docs.astral.sh/uv/concepts/cache/) will be uploaded to
 the GitHub Actions cache. This can speed up runs that reuse the cache by several minutes.
-Caching is enabled by default on GitHub-hosted runners.
+With the default `enable-cache: auto`, caching is enabled on GitHub-hosted runners except for
+`release`, tag push, `pull_request_target`, and `workflow_run` events. Caching is disabled for these
+events to prevent insecure or release-sensitive jobs from restoring potentially poisoned caches.
+Set `enable-cache: true` to explicitly enable caching for any event.
 
 > [!TIP]
 >
@@ -50,7 +54,7 @@ You can optionally define a custom cache key suffix.
 ```yaml
 - name: Enable caching and define a custom cache key suffix
   id: setup-uv
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     enable-cache: true
     cache-suffix: "optional-suffix"
@@ -89,7 +93,7 @@ changes. If you use relative paths, they are relative to the working directory.
 
 ```yaml
 - name: Define a cache dependency glob
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     enable-cache: true
     cache-dependency-glob: "**/pyproject.toml"
@@ -97,7 +101,7 @@ changes. If you use relative paths, they are relative to the working directory.
 
 ```yaml
 - name: Define a list of cache dependency globs
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     enable-cache: true
     cache-dependency-glob: |
@@ -107,7 +111,7 @@ changes. If you use relative paths, they are relative to the working directory.
 
 ```yaml
 - name: Define an absolute cache dependency glob
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     enable-cache: true
     cache-dependency-glob: "/tmp/my-folder/requirements*.txt"
@@ -115,7 +119,7 @@ changes. If you use relative paths, they are relative to the working directory.
 
 ```yaml
 - name: Never invalidate the cache
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     enable-cache: true
     cache-dependency-glob: ""
@@ -128,7 +132,7 @@ By default, the cache will be restored.
 
 ```yaml
 - name: Don't restore an existing cache
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     enable-cache: true
     restore-cache: false
@@ -136,13 +140,15 @@ By default, the cache will be restored.
 
 ## Save cache
 
-You can also disable saving the cache after the run with the `save-cache` input.
+You can control saving the cache after the run with the `save-cache` input.
 This can be useful to save cache storage when you know you will not use the cache of the run again.
-By default, the cache will be saved.
+By default, `save-cache: auto` saves the cache except for `merge_group` events, where caches created
+for temporary merge queue refs are unlikely to be reused. Cache restoration remains enabled for
+these events. Set `save-cache: true` to save the cache for all events.
 
 ```yaml
 - name: Don't save the cache after the run
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     enable-cache: true
     save-cache: false
@@ -168,35 +174,34 @@ It defaults to `setup-uv-cache` in the `TMP` dir, `D:\a\_temp\setup-uv-cache` on
 
 ```yaml
 - name: Define a custom uv cache path
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     cache-local-path: "/path/to/cache"
 ```
 
-## Disable cache pruning
+## Enable cache pruning
 
-By default, the uv cache is pruned after every run, removing pre-built wheels, but retaining any
-wheels that were built from source. On GitHub-hosted runners, it's typically faster to omit those
-pre-built wheels from the cache (and instead re-download them from the registry on each run).
-However, on self-hosted or local runners, preserving the cache may be more efficient. See
-the [documentation](https://docs.astral.sh/uv/concepts/cache/#caching-in-continuous-integration) for
-more information.
+By default, the entire uv cache is persisted across runs. On GitHub-hosted runners, it's typically
+faster to prune the cache before saving it, removing pre-built wheels, but retaining any wheels that
+were built from source. The pre-built wheels are then re-downloaded from the registry on each run.
+See the [documentation](https://docs.astral.sh/uv/concepts/cache/#caching-in-continuous-integration)
+for more information.
 
-If you want to persist the entire cache across runs, disable cache pruning with the `prune-cache`
-input.
+If you want to prune the cache before saving it, enable cache pruning with the `prune-cache` input.
 
 ```yaml
-- name: Don't prune the cache before saving it
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+- name: Prune the cache before saving it
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     enable-cache: true
-    prune-cache: false
+    prune-cache: true
 ```
 
 ## Cache Python installs
 
 By default, the Python install dir (`uv python dir` / `UV_PYTHON_INSTALL_DIR`) is not cached,
-for the same reason that the dependency cache is pruned.
+for the same reason that pruning the dependency cache can improve performance on GitHub-hosted
+runners.
 If you want to cache Python installs along with your dependencies, set the `cache-python` input to `true`.
 
 Note that this only caches Python versions that uv actually installs into `UV_PYTHON_INSTALL_DIR`
@@ -205,7 +210,7 @@ To force managed Python installs, set `UV_PYTHON_PREFERENCE=only-managed`.
 
 ```yaml
 - name: Cache Python installs
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     enable-cache: true
     cache-python: true
@@ -223,7 +228,7 @@ If you want to ignore this, set the `ignore-nothing-to-cache` input to `true`.
 
 ```yaml
 - name: Ignore nothing to cache
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     enable-cache: true
     ignore-nothing-to-cache: true

docs/customization.md

@@ -4,13 +4,14 @@ This document covers advanced customization options including checksum validatio
 
 ## Validate checksum
 
-You can specify a checksum to validate the downloaded executable. Checksums up to the default version
-are automatically verified by this action. The sha256 hashes can be found on the
+Downloaded executables are automatically verified using checksums bundled with this action or,
+for newer, not yet bundled versions, the checksum from [`astral-sh/versions`](https://github.com/astral-sh/versions).
+You can specify a checksum to override those values. The sha256 hashes can also be found on the
 [releases page](https://github.com/astral-sh/uv/releases) of the uv repo.
 
 ```yaml
 - name: Install a specific version and validate the checksum
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     version: "0.3.1"
     checksum: "e11b01402ab645392c7ad6044db63d37e4fd1e745e015306993b07695ea5f9f8"
@@ -39,7 +40,7 @@ The `archive_format` field is currently ignored.
 
 ```yaml
 - name: Use a custom manifest file
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     manifest-file: "https://example.com/my-custom-manifest.ndjson"
 ```
@@ -58,7 +59,7 @@ You can disable this by setting the `add-problem-matchers` input to `false`.
 
 ```yaml
 - name: Install the latest version of uv without problem matchers
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     add-problem-matchers: false
 ```

docs/environment-and-tools.md

@@ -9,7 +9,7 @@ This allows directly using it in later steps:
 
 ```yaml
 - name: Install the latest version of uv and activate the environment
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     activate-environment: true
 - run: uv pip install pip
@@ -17,10 +17,22 @@ This allows directly using it in later steps:
 
 By default, the venv is created at `.venv` inside the `working-directory`.
 
+With `activate-environment: true`, the `python-runtime-id` output identifies the
+venv's Python runtime as reported by uv. This is an opaque identifier that users of the action
+can use as a cache key if necessary; users should not assume anything about
+the stability or structure of the identifier itself.
+
+For example, you can combine it with the platform and dependency information relevant to
+your cache with `id: setup-uv` on the setup step:
+
+```yaml
+key: build-${{ runner.os }}-${{ runner.arch }}-${{ steps.setup-uv.outputs.python-runtime-id }}-${{ hashFiles('uv.lock') }}
+```
+
 You can customize the venv location with `venv-path`, for example to place it in the runner temp directory:
 
 ```yaml
-- uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+- uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     activate-environment: true
     venv-path: ${{ runner.temp }}/custom-venv
@@ -51,7 +63,7 @@ are not sufficient, you can provide a custom GitHub token with the necessary per
 
 ```yaml
 - name: Install the latest version of uv with a custom GitHub token
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     github-token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}
 ```
@@ -69,7 +81,7 @@ input:
 
 ```yaml
 - name: Install the latest version of uv with a custom tool dir
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     tool-dir: "/path/to/tool/dir"
 ```
@@ -88,7 +100,7 @@ If you want to change this behaviour (especially on self-hosted runners) you can
 
 ```yaml
 - name: Install the latest version of uv with a custom tool bin dir
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     tool-bin-dir: "/path/to/tool-bin/dir"
 ```
@@ -105,7 +117,7 @@ This action supports expanding the `~` character to the user's home directory fo
 
 ```yaml
 - name: Expand the tilde character
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     cache-local-path: "~/path/to/cache"
     tool-dir: "~/path/to/tool/dir"
@@ -122,7 +134,7 @@ If you want to ignore this, set the `ignore-empty-workdir` input to `true`.
 
 ```yaml
 - name: Ignore empty workdir
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     ignore-empty-workdir: true
 ```
@@ -131,7 +143,8 @@ If you want to ignore this, set the `ignore-empty-workdir` input to `true`.
 
 This action sets several environment variables that influence uv's behavior and can be used by subsequent steps:
 
-- `UV_PYTHON`: Set when `python-version` input is specified. Controls which Python version uv uses.
+- `UV_PYTHON`: Set when `python-version` is specified or the selected `.tool-versions` file contains a supported `python` entry. Controls which Python version uv uses.
+- `UV_PYTHON_ARCH`: Set when `python-arch` is specified. Controls the architecture of Python requests that do not specify one.
 - `UV_CACHE_DIR`: Set when caching is enabled (unless already configured in uv config files). Controls where uv stores its cache.
 - `UV_TOOL_DIR`: Set when `tool-dir` input is specified. Controls where uv installs tool environments.
 - `UV_TOOL_BIN_DIR`: Set when `tool-bin-dir` input is specified. Controls where uv installs tool binaries.
@@ -142,10 +155,12 @@ This action sets several environment variables that influence uv's behavior and
 
 - `UV_NO_MODIFY_PATH`: If set, prevents the action from modifying PATH. Cannot be used with `activate-environment`.
 - `UV_CACHE_DIR`: If already set, the action will respect it instead of setting its own cache directory.
+- `UV_PYTHON`: If already set and `python-version` is not specified, the action will respect it instead of using the `python` entry from `.tool-versions`.
+- `UV_PYTHON_ARCH`: If already set and `python-arch` is not specified, the action will use it and include it in the cache key. Requires a uv version that supports `UV_PYTHON_ARCH`.
 
 ```yaml
 - name: Example using environment variables
-  uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     python-version: "3.12"
     tool-dir: "/custom/tool/dir"

package.json

@@ -5,6 +5,16 @@
   "type": "module",
   "description": "Set up your GitHub Actions workflow with a specific version of uv",
   "main": "dist/setup/index.cjs",
+  "engines": {
+    "npm": ">=11.10.0"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "npm",
+      "version": ">=11.10.0",
+      "onFail": "error"
+    }
+  },
   "scripts": {
     "build": "tsc --noEmit",
     "check": "biome check --write",
@@ -12,7 +22,7 @@
     "test:unit": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js",
     "test": "npm run build && npm run test:unit",
     "act": "act pull_request -W .github/workflows/test.yml --container-architecture linux/amd64 -s GITHUB_TOKEN=\"$(gh auth token)\"",
-    "update-known-checksums": "RUNNER_TEMP=known_versions node dist/update-known-checksums/index.cjs src/download/checksum/known-checksums.ts",
+    "update-known-checksums": "RUNNER_TEMP=known_versions node dist/update-known-checksums/index.cjs src/download/checksum/known-checksums.json",
     "all": "npm run build && npm run check && npm run package && npm run test:unit"
   },
   "repository": {
@@ -28,25 +38,25 @@
   "author": "@eifinger",
   "license": "MIT",
   "dependencies": {
-    "@actions/cache": "^6.0.1",
+    "@actions/cache": "^6.2.0",
     "@actions/core": "^3.0.0",
     "@actions/exec": "^3.0.0",
-    "@actions/glob": "^0.6.1",
+    "@actions/glob": "^0.7.0",
     "@actions/io": "^3.0.2",
     "@actions/tool-cache": "^4.0.0",
     "@renovatebot/pep440": "^5.0.0",
-    "smol-toml": "^1.6.1",
-    "undici": "^8.3.0"
+    "smol-toml": "^1.8.0",
+    "undici": "^8.10.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.16",
+    "@biomejs/biome": "^2.5.9",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.5.0",
-    "@types/semver": "^7.7.1",
-    "@vercel/ncc": "^0.38.4",
-    "esbuild": "^0.28.0",
+    "@types/node": "^26.2.0",
+    "@types/semver": "^7.8.0",
+    "@vercel/ncc": "^0.45.0",
+    "esbuild": "^0.28.2",
     "jest": "^30.4.2",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^5.3.0",
     "ts-jest": "^29.4.11",
     "typescript": "^6.0.3"
   }

src/cache/restore-cache.ts

@@ -1,7 +1,7 @@
 import * as cache from "@actions/cache";
 import * as core from "@actions/core";
 import { hashFiles } from "../hash/hash-files";
-import type { SetupInputs } from "../utils/inputs";
+import { resolvePythonArch, type SetupInputs } from "../utils/inputs";
 import * as log from "../utils/logging";
 import { getArch, getOSNameVersion, getPlatform } from "../utils/platforms";
 
@@ -98,11 +98,15 @@ async function computeKeys(
     ? `-${encodeURIComponent(inputs.cacheSuffix)}`
     : "";
   const version = encodeURIComponent(pythonVersion ?? "unknown");
+  const pythonArch = resolvePythonArch(inputs.pythonArch);
+  const pythonArchKey = pythonArch
+    ? `-python-${encodeURIComponent(pythonArch)}`
+    : "";
   const platform = await getPlatform();
   const osNameVersion = getOSNameVersion();
   const pruned = inputs.pruneCache ? "-pruned" : "";
   const python = inputs.cachePython ? "-py" : "";
-  return `setup-uv-${CACHE_VERSION}-${getArch()}-${platform}-${osNameVersion}-${version}${pruned}${python}${cacheDependencyPathHash}${suffix}`;
+  return `setup-uv-${CACHE_VERSION}-${getArch()}-${platform}-${osNameVersion}-${version}${pythonArchKey}${pruned}${python}${cacheDependencyPathHash}${suffix}`;
 }
 
 function handleMatchResult(

src/download/checksum/checksum.ts

@@ -11,19 +11,30 @@ export async function validateChecksum(
   arch: Architecture,
   platform: Platform,
   version: string,
+  manifestChecksum?: string,
 ): Promise<void> {
   const key = `${arch}-${platform}-${version}`;
   const hasProvidedChecksum = checksum !== undefined && checksum !== "";
-  const checksumToUse = hasProvidedChecksum ? checksum : KNOWN_CHECKSUMS[key];
+  const knownChecksum = KNOWN_CHECKSUMS[key];
+  const hasManifestChecksum =
+    manifestChecksum !== undefined && manifestChecksum !== "";
+  const checksumToUse = hasProvidedChecksum
+    ? checksum
+    : (knownChecksum ?? (hasManifestChecksum ? manifestChecksum : undefined));
 
   if (checksumToUse === undefined) {
+    if (manifestChecksum !== undefined) {
+      throw new Error(`No checksum found for ${key} in manifest.`);
+    }
     core.debug(`No checksum found for ${key}.`);
     return;
   }
 
   const checksumSource = hasProvidedChecksum
     ? "provided checksum"
-    : `KNOWN_CHECKSUMS entry for ${key}`;
+    : knownChecksum !== undefined
+      ? `KNOWN_CHECKSUMS entry for ${key}`
+      : "manifest checksum";
 
   core.debug(`Validating checksum using ${checksumSource}.`);
   const isValid = await validateFileCheckSum(downloadPath, checksumToUse);

src/download/checksum/known-version.ts

@@ -0,0 +1,23 @@
+import * as semver from "semver";
+import { KNOWN_CHECKSUMS } from "./known-checksums";
+
+const VERSION_IN_CHECKSUM_KEY_PATTERN =
+  /-(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)$/;
+
+export function getLatestKnownVersion(): string {
+  const versions = new Set<string>();
+
+  for (const key of Object.keys(KNOWN_CHECKSUMS)) {
+    const version = key.match(VERSION_IN_CHECKSUM_KEY_PATTERN)?.[1];
+    if (version !== undefined) {
+      versions.add(version);
+    }
+  }
+
+  const latestVersion = [...versions].sort(semver.rcompare)[0];
+  if (!latestVersion) {
+    throw new Error("Could not determine latest known version from checksums.");
+  }
+
+  return latestVersion;
+}

src/download/checksum/update-known-checksums.ts

@@ -19,16 +19,7 @@ export async function updateChecksums(
     deduplicatedEntries.set(entry.key, entry.checksum);
   }
 
-  const body = [...deduplicatedEntries.entries()]
-    .map(([key, checksum]) => `  "${key}":\n    "${checksum}"`)
-    .join(",\n");
-
-  const content =
-    "// AUTOGENERATED_DO_NOT_EDIT\n" +
-    "export const KNOWN_CHECKSUMS: { [key: string]: string } = {\n" +
-    body +
-    (body === "" ? "" : ",\n") +
-    "};\n";
+  const content = `${JSON.stringify(Object.fromEntries(deduplicatedEntries), null, 2)}\n`;
 
   await fs.writeFile(filePath, content);
 }

src/download/download-version.ts

@@ -47,12 +47,14 @@ export async function downloadVersion(
     );
   }
 
-  // For the default astral-sh/versions source, checksum validation relies on
-  // user input or the built-in KNOWN_CHECKSUMS table, not manifest sha256 values.
+  // Custom manifests are explicitly selected by the user, so their checksum
+  // takes precedence over the built-in table. For the default manifest, pass
+  // its checksum as a fallback after user input and KNOWN_CHECKSUMS.
   const resolvedChecksum =
     manifestUrl === undefined
       ? checksum
       : resolveChecksum(checksum, artifact.checksum);
+  const manifestChecksum = artifact.checksum;
 
   const mirrorUrl = downloadFromAstralMirror
     ? rewriteToMirror(artifact.downloadUrl)
@@ -67,6 +69,7 @@ export async function downloadVersion(
       arch,
       version,
       resolvedChecksum,
+      manifestChecksum,
       githubTokenForUrl(downloadUrl, githubToken),
     );
   } catch (err) {
@@ -85,6 +88,7 @@ export async function downloadVersion(
       arch,
       version,
       resolvedChecksum,
+      manifestChecksum,
       githubTokenForUrl(artifact.downloadUrl, githubToken),
     );
   }
@@ -122,6 +126,7 @@ async function downloadArtifact(
   arch: Architecture,
   version: string,
   checksum: string | undefined,
+  manifestChecksum: string | undefined,
   githubToken: string | undefined,
 ): Promise<{ version: string; cachedToolDir: string }> {
   log.info(`Downloading uv from "${downloadUrl}" ...`);
@@ -130,7 +135,14 @@ async function downloadArtifact(
     undefined,
     githubToken,
   );
-  await validateChecksum(checksum, downloadPath, arch, platform, version);
+  await validateChecksum(
+    checksum,
+    downloadPath,
+    arch,
+    platform,
+    version,
+    manifestChecksum,
+  );
 
   let uvDir: string;
   if (platform === "pc-windows-msvc") {

src/download/manifest.ts

@@ -1,3 +1,5 @@
+import { createInterface } from "node:readline";
+import { Readable } from "node:stream";
 import * as core from "@actions/core";
 import { VERSIONS_MANIFEST_URL } from "../utils/constants";
 import { fetch } from "../utils/fetch";
@@ -23,28 +25,27 @@ export interface ArtifactResult {
   downloadUrl: string;
 }
 
-const cachedManifestData = new Map<string, ManifestVersion[]>();
+interface CachedManifest {
+  complete: boolean;
+  versions: ManifestVersion[];
+}
+
+const cachedManifestData = new Map<string, CachedManifest>();
+export const MANIFEST_FETCH_ATTEMPTS = 3;
 
 export async function fetchManifest(
   manifestUrl: string = VERSIONS_MANIFEST_URL,
 ): Promise<ManifestVersion[]> {
-  const cachedVersions = cachedManifestData.get(manifestUrl);
-  if (cachedVersions !== undefined) {
+  const cachedManifest = cachedManifestData.get(manifestUrl);
+  if (cachedManifest?.complete === true) {
     core.debug(`Using cached manifest data from ${manifestUrl}`);
-    return cachedVersions;
-  }
-
-  log.info(`Fetching manifest data from ${manifestUrl} ...`);
-  const response = await fetch(manifestUrl, {});
-  if (!response.ok) {
-    throw new Error(
-      `Failed to fetch manifest data: ${response.status} ${response.statusText}`,
-    );
+    return cachedManifest.versions;
   }
 
+  const response = await fetchManifestResponse(manifestUrl);
   const body = await response.text();
   const versions = parseManifest(body, manifestUrl);
-  cachedManifestData.set(manifestUrl, versions);
+  cachedManifestData.set(manifestUrl, { complete: true, versions });
   return versions;
 }
 
@@ -57,11 +58,7 @@ export function parseManifest(
     throw new Error(`Manifest at ${sourceDescription} is empty.`);
   }
 
-  if (trimmed.startsWith("[")) {
-    throw new Error(
-      `Legacy JSON array manifests are no longer supported in ${sourceDescription}. Use the astral-sh/versions manifest format instead.`,
-    );
-  }
+  rejectLegacyManifest(trimmed, sourceDescription);
 
   const versions: ManifestVersion[] = [];
 
@@ -71,22 +68,7 @@ export function parseManifest(
       continue;
     }
 
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(record);
-    } catch (error) {
-      throw new Error(
-        `Failed to parse manifest data from ${sourceDescription} at line ${index + 1}: ${(error as Error).message}`,
-      );
-    }
-
-    if (!isManifestVersion(parsed)) {
-      throw new Error(
-        `Invalid manifest record in ${sourceDescription} at line ${index + 1}.`,
-      );
-    }
-
-    versions.push(parsed);
+    versions.push(parseManifestRecord(record, sourceDescription, index + 1));
   }
 
   if (versions.length === 0) {
@@ -99,7 +81,10 @@ export function parseManifest(
 export async function getLatestVersion(
   manifestUrl: string = VERSIONS_MANIFEST_URL,
 ): Promise<string> {
-  const latestVersion = (await fetchManifest(manifestUrl))[0]?.version;
+  const latestVersion =
+    manifestUrl === VERSIONS_MANIFEST_URL
+      ? (await findManifestVersion(() => true))?.version
+      : (await fetchManifest(manifestUrl))[0]?.version;
 
   if (latestVersion === undefined) {
     throw new Error("No versions found in manifest data");
@@ -109,6 +94,16 @@ export async function getLatestVersion(
   return latestVersion;
 }
 
+// The default manifest is guaranteed to be ordered newest-first:
+// https://github.com/astral-sh/versions#format
+export async function getFirstMatchingVersion(
+  predicate: (version: string) => boolean,
+): Promise<string | undefined> {
+  return (
+    await findManifestVersion((versionData) => predicate(versionData.version))
+  )?.version;
+}
+
 export async function getAllVersions(
   manifestUrl: string = VERSIONS_MANIFEST_URL,
 ): Promise<string[]> {
@@ -125,8 +120,10 @@ export async function getArtifact(
   platform: string,
   manifestUrl: string = VERSIONS_MANIFEST_URL,
 ): Promise<ArtifactResult | undefined> {
-  const versions = await fetchManifest(manifestUrl);
-  const versionData = versions.find(
+  const versionData =
+    manifestUrl === VERSIONS_MANIFEST_URL
+      ? await findManifestVersion((candidate) => candidate.version === version)
+      : (await fetchManifest(manifestUrl)).find(
           (candidate) => candidate.version === version,
         );
   if (!versionData) {
@@ -169,6 +166,105 @@ export function clearManifestCache(manifestUrl?: string): void {
   cachedManifestData.delete(manifestUrl);
 }
 
+async function fetchManifestResponse(manifestUrl: string) {
+  let response: Awaited<ReturnType<typeof fetch>> | undefined;
+  for (let attempt = 1; attempt <= MANIFEST_FETCH_ATTEMPTS; attempt++) {
+    log.info(`Fetching manifest data from ${manifestUrl} ...`);
+    try {
+      response = await fetch(manifestUrl, {});
+      break;
+    } catch (error) {
+      if (attempt >= MANIFEST_FETCH_ATTEMPTS) {
+        throw error;
+      }
+      const delayMs = 1_000 * 2 ** (attempt - 1);
+      log.info(`Manifest fetch failed; retrying in ${delayMs}ms ...`);
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+
+  if (response === undefined) {
+    throw new Error("Manifest fetch attempts exhausted.");
+  }
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch manifest data: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  return response;
+}
+
+async function findManifestVersion(
+  predicate: (versionData: ManifestVersion) => boolean,
+): Promise<ManifestVersion | undefined> {
+  const cachedManifest = cachedManifestData.get(VERSIONS_MANIFEST_URL);
+  const cachedVersion = cachedManifest?.versions.find(predicate);
+  if (cachedVersion !== undefined || cachedManifest?.complete === true) {
+    return cachedVersion;
+  }
+
+  const response = await fetchManifestResponse(VERSIONS_MANIFEST_URL);
+  if (response.body === null) {
+    const versions = parseManifest(
+      await response.text(),
+      VERSIONS_MANIFEST_URL,
+    );
+    cachedManifestData.set(VERSIONS_MANIFEST_URL, {
+      complete: true,
+      versions,
+    });
+    return versions.find(predicate);
+  }
+
+  const input = Readable.fromWeb(response.body);
+  const lines = createInterface({ crlfDelay: Number.POSITIVE_INFINITY, input });
+  const versions: ManifestVersion[] = [];
+  let complete = false;
+  let lineNumber = 0;
+  let matchedVersion: ManifestVersion | undefined;
+
+  try {
+    for await (const line of lines) {
+      lineNumber += 1;
+      const record = line.trim();
+      if (record === "") {
+        continue;
+      }
+
+      if (versions.length === 0) {
+        rejectLegacyManifest(record, VERSIONS_MANIFEST_URL);
+      }
+
+      const versionData = parseManifestRecord(
+        record,
+        VERSIONS_MANIFEST_URL,
+        lineNumber,
+      );
+      versions.push(versionData);
+      if (predicate(versionData)) {
+        matchedVersion = versionData;
+        break;
+      }
+    }
+
+    complete = matchedVersion === undefined;
+  } finally {
+    lines.close();
+    if (!complete) {
+      input.destroy();
+    }
+  }
+
+  if (versions.length === 0) {
+    throw new Error(`Manifest at ${VERSIONS_MANIFEST_URL} is empty.`);
+  }
+
+  cachedManifestData.set(VERSIONS_MANIFEST_URL, { complete, versions });
+  return matchedVersion;
+}
+
 function manifestSource(manifestUrl: string): string {
   if (manifestUrl === VERSIONS_MANIFEST_URL) {
     return VERSIONS_MANIFEST_URL;
@@ -177,6 +273,37 @@ function manifestSource(manifestUrl: string): string {
   return `manifest-file ${manifestUrl}`;
 }
 
+function parseManifestRecord(
+  record: string,
+  sourceDescription: string,
+  lineNumber: number,
+): ManifestVersion {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(record);
+  } catch (error) {
+    throw new Error(
+      `Failed to parse manifest data from ${sourceDescription} at line ${lineNumber}: ${(error as Error).message}`,
+    );
+  }
+
+  if (!isManifestVersion(parsed)) {
+    throw new Error(
+      `Invalid manifest record in ${sourceDescription} at line ${lineNumber}.`,
+    );
+  }
+
+  return parsed;
+}
+
+function rejectLegacyManifest(data: string, sourceDescription: string): void {
+  if (data.startsWith("[")) {
+    throw new Error(
+      `Legacy JSON array manifests are no longer supported in ${sourceDescription}. Use the astral-sh/versions manifest format instead.`,
+    );
+  }
+}
+
 function isManifestVersion(value: unknown): value is ManifestVersion {
   if (!isRecord(value)) {
     return false;

src/setup-uv.ts

@@ -16,6 +16,8 @@ import {
   getPlatform,
   type Platform,
 } from "./utils/platforms";
+import { setupPythonArch } from "./utils/python-arch";
+import { getPythonRuntimeId } from "./utils/python-runtime";
 import { resolveUvVersion } from "./version/resolve";
 
 const sourceDir = __dirname;
@@ -85,6 +87,11 @@ async function run(): Promise<void> {
       throw new Error(`Unsupported architecture: ${process.arch}`);
     }
     const setupResult = await setupUv(inputs, platform, arch);
+    const uvPath = path.join(
+      setupResult.uvDir,
+      process.platform === "win32" ? "uv.exe" : "uv",
+    );
+    await setupPythonArch(uvPath, inputs.pythonArch);
 
     addToolBinToPath(inputs);
     addUvToPathAndOutput(setupResult.uvDir);
@@ -101,6 +108,7 @@ async function run(): Promise<void> {
 
     const detectedPythonVersion = await getPythonVersion(inputs);
     core.setOutput("python-version", detectedPythonVersion);
+    core.setOutput("python-runtime-id", await getPythonRuntimeId(inputs));
 
     if (inputs.enableCache) {
       await restoreCache(inputs, detectedPythonVersion);

src/update-known-checksums.ts

@@ -1,6 +1,6 @@
 import * as core from "@actions/core";
 import * as semver from "semver";
-import { KNOWN_CHECKSUMS } from "./download/checksum/known-checksums";
+import { getLatestKnownVersion } from "./download/checksum/known-version";
 import {
   type ChecksumEntry,
   updateChecksums,
@@ -12,9 +12,6 @@ import {
 } from "./download/manifest";
 import * as log from "./utils/logging";
 
-const VERSION_IN_CHECKSUM_KEY_PATTERN =
-  /-(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)$/;
-
 async function run(): Promise<void> {
   const checksumFilePath = process.argv.slice(2)[0];
   if (!checksumFilePath) {
@@ -24,7 +21,7 @@ async function run(): Promise<void> {
   }
 
   const latestVersion = await getLatestVersion();
-  const latestKnownVersion = getLatestKnownVersionFromChecksums();
+  const latestKnownVersion = getLatestKnownVersion();
 
   if (semver.lte(latestVersion, latestKnownVersion)) {
     log.info(
@@ -40,28 +37,6 @@ async function run(): Promise<void> {
   core.setOutput("latest-version", latestVersion);
 }
 
-function getLatestKnownVersionFromChecksums(): string {
-  const versions = new Set<string>();
-
-  for (const key of Object.keys(KNOWN_CHECKSUMS)) {
-    const version = extractVersionFromChecksumKey(key);
-    if (version !== undefined) {
-      versions.add(version);
-    }
-  }
-
-  const latestVersion = [...versions].sort(semver.rcompare)[0];
-  if (!latestVersion) {
-    throw new Error("Could not determine latest known version from checksums.");
-  }
-
-  return latestVersion;
-}
-
-function extractVersionFromChecksumKey(key: string): string | undefined {
-  return key.match(VERSION_IN_CHECKSUM_KEY_PATTERN)?.[1];
-}
-
 function extractChecksumsFromManifest(
   versions: ManifestVersion[],
 ): ChecksumEntry[] {

src/utils/fetch.ts

@@ -1,18 +1,8 @@
-import { ProxyAgent, type RequestInit, fetch as undiciFetch } from "undici";
-
-export function getProxyAgent() {
-  const httpProxy = process.env.HTTP_PROXY || process.env.http_proxy;
-  if (httpProxy) {
-    return new ProxyAgent(httpProxy);
-  }
-
-  const httpsProxy = process.env.HTTPS_PROXY || process.env.https_proxy;
-  if (httpsProxy) {
-    return new ProxyAgent(httpsProxy);
-  }
-
-  return undefined;
-}
+import {
+  EnvHttpProxyAgent,
+  type RequestInit,
+  fetch as undiciFetch,
+} from "undici";
 
 export const fetch = async (url: string, opts: RequestInit) => {
   // Merge timeout signal with any existing signal from opts
@@ -23,7 +13,7 @@ export const fetch = async (url: string, opts: RequestInit) => {
     : timeoutSignal;
 
   return await undiciFetch(url, {
-    dispatcher: getProxyAgent(),
+    dispatcher: new EnvHttpProxyAgent(),
     ...opts,
     signal: mergedSignal,
   });

src/utils/inputs.ts

@@ -1,5 +1,7 @@
+import fs from "node:fs";
 import path from "node:path";
 import * as core from "@actions/core";
+import { getPythonVersionFromToolVersions } from "../version/tool-versions-file";
 import { getConfigValueFromTomlFile } from "./config-file";
 import * as log from "./logging";
 
@@ -22,6 +24,7 @@ export interface SetupInputs {
   version: string;
   versionFile: string;
   pythonVersion: string;
+  pythonArch: string;
   activateEnvironment: boolean;
   noProject: boolean;
   venvPath: string;
@@ -51,14 +54,15 @@ export function loadInputs(): SetupInputs {
   const workingDirectory = core.getInput("working-directory");
   const version = core.getInput("version");
   const versionFile = getVersionFile(workingDirectory);
-  const pythonVersion = core.getInput("python-version");
+  const pythonVersion = getPythonVersion(versionFile);
+  const pythonArch = core.getInput("python-arch");
   const activateEnvironment = core.getBooleanInput("activate-environment");
   const noProject = core.getBooleanInput("no-project");
   const venvPath = getVenvPath(workingDirectory, activateEnvironment);
   const checksum = core.getInput("checksum");
   const enableCache = getEnableCache();
   const restoreCache = core.getInput("restore-cache") === "true";
-  const saveCache = core.getInput("save-cache") === "true";
+  const saveCache = getSaveCache();
   const cacheSuffix = core.getInput("cache-suffix") || "";
   const cacheLocalPath = getCacheLocalPath(
     workingDirectory,
@@ -98,6 +102,7 @@ export function loadInputs(): SetupInputs {
     manifestFile,
     noProject,
     pruneCache,
+    pythonArch,
     pythonDir,
     pythonVersion,
     quiet,
@@ -122,6 +127,32 @@ function getVersionFile(workingDirectory: string): string {
   return versionFileInput;
 }
 
+function getPythonVersion(versionFile: string): string {
+  const pythonVersionInput = core.getInput("python-version");
+  if (pythonVersionInput !== "") {
+    return pythonVersionInput;
+  }
+  if (process.env.UV_PYTHON !== undefined && process.env.UV_PYTHON !== "") {
+    return "";
+  }
+  if (versionFile === "" || !fs.existsSync(versionFile)) {
+    return "";
+  }
+
+  try {
+    return getPythonVersionFromToolVersions(versionFile) ?? "";
+  } catch (err) {
+    log.warning(
+      `Error while parsing Python version from ${versionFile}: ${(err as Error).message}`,
+    );
+    return "";
+  }
+}
+
+export function resolvePythonArch(pythonArch: string): string {
+  return pythonArch || process.env.UV_PYTHON_ARCH || "";
+}
+
 function getVenvPath(
   workingDirectory: string,
   activateEnvironment: boolean,
@@ -140,11 +171,43 @@ function getVenvPath(
 function getEnableCache(): boolean {
   const enableCacheInput = core.getInput("enable-cache");
   if (enableCacheInput === "auto") {
-    return process.env.RUNNER_ENVIRONMENT === "github-hosted";
+    if (process.env.RUNNER_ENVIRONMENT !== "github-hosted") {
+      return false;
+    }
+
+    const eventName = process.env.GITHUB_EVENT_NAME;
+    const isTagPush =
+      eventName === "push" && process.env.GITHUB_REF?.startsWith("refs/tags/");
+    if (isTagPush) {
+      log.info("Caching is disabled for tag pushes");
+      return false;
+    }
+    if (
+      eventName === "pull_request_target" ||
+      eventName === "workflow_run" ||
+      eventName === "release"
+    ) {
+      log.info(`Caching is disabled for the ${eventName} event`);
+      return false;
+    }
+
+    return true;
   }
   return enableCacheInput === "true";
 }
 
+function getSaveCache(): boolean {
+  const saveCacheInput = core.getInput("save-cache");
+  if (saveCacheInput === "auto") {
+    if (process.env.GITHUB_EVENT_NAME === "merge_group") {
+      log.info("Cache saving is disabled for the merge_group event");
+      return false;
+    }
+    return true;
+  }
+  return saveCacheInput === "true";
+}
+
 function getToolBinDir(workingDirectory: string): string | undefined {
   const toolBinDirInput = core.getInput("tool-bin-dir");
   if (toolBinDirInput !== "") {

src/utils/platforms.ts

@@ -102,6 +102,7 @@ export function getOSNameVersion(): string {
 
 function getLinuxOSNameVersion(): string {
   const files = ["/etc/os-release", "/usr/lib/os-release"];
+  let idWithoutVersion: string | undefined;
 
   for (const file of files) {
     try {
@@ -122,11 +123,22 @@ function getLinuxOSNameVersion(): string {
       if (id && buildId) {
         return `${id}-${buildId}`;
       }
+      // Remember the ID but keep looking: the next file might still
+      // provide a version field
+      if (id && idWithoutVersion === undefined) {
+        idWithoutVersion = id;
+      }
     } catch {
       // Try next file
     }
   }
 
+  // Fallback for rolling releases (e.g. void) that have no version
+  // field at all
+  if (idWithoutVersion) {
+    return idWithoutVersion;
+  }
+
   throw new Error(
     "Failed to determine Linux distribution. " +
       "Could not read /etc/os-release or /usr/lib/os-release",

src/utils/python-arch.ts

@@ -0,0 +1,76 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import * as core from "@actions/core";
+import { resolvePythonArch } from "./inputs";
+import * as log from "./logging";
+
+const execFileAsync = promisify(execFile);
+const PROBE_ARCH = "setup-uv-probe";
+
+export async function setupPythonArch(
+  uvPath: string,
+  pythonArchInput: string,
+): Promise<void> {
+  const pythonArch = resolvePythonArch(pythonArchInput);
+  if (pythonArch === "") {
+    return;
+  }
+
+  // Older uv releases ignore unknown environment variables. An invalid architecture
+  // confirms that uv recognizes UV_PYTHON_ARCH without finding or downloading Python.
+  const probe = await queryPythonArch(uvPath, PROBE_ARCH);
+  if (probe.exitCode === 0) {
+    throw new Error(
+      "The installed version of uv does not support UV_PYTHON_ARCH. Select a newer uv version or use an architecture-qualified python-version.",
+    );
+  }
+  if (
+    !probe.stderr.includes(
+      `environment variable \`UV_PYTHON_ARCH\` with invalid value \`${PROBE_ARCH}\``,
+    )
+  ) {
+    throw new Error(
+      `Failed to check uv's support for UV_PYTHON_ARCH: ${probe.stderr.trim() || `uv exited with code ${probe.exitCode}`}`,
+    );
+  }
+
+  const selected = await queryPythonArch(uvPath, pythonArch);
+  if (selected.exitCode !== 0) {
+    throw new Error(
+      `Failed to set Python architecture to ${pythonArch}: ${selected.stderr.trim() || `uv exited with code ${selected.exitCode}`}`,
+    );
+  }
+
+  if (pythonArchInput !== "") {
+    core.exportVariable("UV_PYTHON_ARCH", pythonArch);
+    log.info(`Set UV_PYTHON_ARCH to ${pythonArch}`);
+  }
+}
+
+async function queryPythonArch(
+  uvPath: string,
+  pythonArch: string,
+): Promise<{ exitCode: number; stderr: string }> {
+  try {
+    const { stderr } = await execFileAsync(
+      uvPath,
+      ["--no-config", "cache", "dir"],
+      {
+        encoding: "utf8",
+        env: { ...process.env, NO_COLOR: "1", UV_PYTHON_ARCH: pythonArch },
+      },
+    );
+    return { exitCode: 0, stderr };
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      typeof error.code === "number" &&
+      "stderr" in error &&
+      typeof error.stderr === "string"
+    ) {
+      return { exitCode: error.code, stderr: error.stderr };
+    }
+    throw error;
+  }
+}

src/utils/python-runtime.ts

@@ -0,0 +1,43 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { SetupInputs } from "./inputs";
+
+const execFileAsync = promisify(execFile);
+
+export async function getPythonRuntimeId(inputs: SetupInputs): Promise<string> {
+  if (!inputs.activateEnvironment) {
+    return "";
+  }
+
+  try {
+    // The venv path restricts results to this invocation's runtime, even if
+    // earlier setup-uv calls installed other Python versions in the same job.
+    const { stdout } = await execFileAsync(
+      "uv",
+      [
+        "python",
+        "list",
+        inputs.venvPath,
+        "--only-installed",
+        "--output-format",
+        "json",
+      ],
+      { encoding: "utf8" },
+    );
+    const pythons = JSON.parse(stdout);
+    if (
+      !Array.isArray(pythons) ||
+      pythons.length !== 1 ||
+      typeof pythons[0]?.key !== "string" ||
+      pythons[0].key === ""
+    ) {
+      throw new Error("Expected one installed Python with a runtime key");
+    }
+    return pythons[0].key;
+  } catch (error) {
+    throw new Error(
+      `Failed to identify the activated environment's Python runtime: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+}

src/version/resolve.ts

@@ -2,7 +2,13 @@ import * as core from "@actions/core";
 import * as tc from "@actions/tool-cache";
 import * as pep440 from "@renovatebot/pep440";
 import * as semver from "semver";
-import { getAllVersions, getLatestVersion } from "../download/manifest";
+import { getLatestKnownVersion } from "../download/checksum/known-version";
+import {
+  getAllVersions,
+  getFirstMatchingVersion,
+  getLatestVersion,
+} from "../download/manifest";
+import { VERSIONS_MANIFEST_URL } from "../utils/constants";
 import type { ResolutionStrategy } from "../utils/inputs";
 import * as log from "../utils/logging";
 import {
@@ -82,13 +88,26 @@ class RangeVersionResolver implements ConcreteVersionResolver {
       return undefined;
     }
 
+    let resolvedVersion: string | undefined;
+    if (
+      context.resolutionStrategy === "highest" &&
+      (context.manifestUrl === undefined ||
+        context.manifestUrl === VERSIONS_MANIFEST_URL)
+    ) {
+      resolvedVersion = await findHighestSatisfyingVersion(
+        context.parsedSpecifier.normalized,
+      );
+    } else {
       const availableVersions = await getAllVersions(context.manifestUrl);
       core.debug(`Available versions: ${availableVersions}`);
-
-    const resolvedVersion =
+      resolvedVersion =
         context.resolutionStrategy === "lowest"
           ? minSatisfying(availableVersions, context.parsedSpecifier.normalized)
-        : maxSatisfying(availableVersions, context.parsedSpecifier.normalized);
+          : maxSatisfying(
+              availableVersions,
+              context.parsedSpecifier.normalized,
+            );
+    }
 
     if (resolvedVersion === undefined) {
       throw new Error(`No version found for ${context.parsedSpecifier.raw}`);
@@ -125,6 +144,10 @@ export async function resolveVersion(
 ): Promise<string> {
   core.debug(`Resolving version: ${versionInput}`);
 
+  if (versionInput.trim() === "latest-known") {
+    return getLatestKnownVersion();
+  }
+
   const context: ConcreteVersionResolutionContext = {
     manifestUrl,
     parsedSpecifier: parseVersionSpecifier(versionInput),
@@ -141,6 +164,35 @@ export async function resolveVersion(
   throw new Error(`No version found for ${versionInput}`);
 }
 
+async function findHighestSatisfyingVersion(
+  versionSpecifier: string,
+): Promise<string | undefined> {
+  // This fast path assumes uv releases are semver-monotonic: newer manifest
+  // entries always have higher versions, with no lower-version backports.
+  const semverRange = semver.validRange(versionSpecifier);
+  if (semverRange !== null) {
+    const semverMatch = await getFirstMatchingVersion((version) =>
+      semver.satisfies(version, semverRange),
+    );
+    if (semverMatch !== undefined) {
+      core.debug(
+        `Found a version that satisfies the semver range: ${semverMatch}`,
+      );
+      return semverMatch;
+    }
+  }
+
+  const pep440Match = await getFirstMatchingVersion((version) =>
+    pep440.satisfies(version, versionSpecifier),
+  );
+  if (pep440Match !== undefined) {
+    core.debug(
+      `Found a version that satisfies the pep440 specifier: ${pep440Match}`,
+    );
+  }
+  return pep440Match;
+}
+
 function maxSatisfying(
   versions: string[],
   version: string,

src/version/tool-versions-file.ts

@@ -4,28 +4,83 @@ import * as core from "@actions/core";
 export function getUvVersionFromToolVersions(
   filePath: string,
 ): string | undefined {
-  if (!filePath.endsWith(".tool-versions")) {
+  const versions = getToolVersions(filePath, "uv");
+  if (versions === undefined || versions.length !== 1) {
     return undefined;
   }
-  const fileContents = fs.readFileSync(filePath, "utf8");
-  const lines = fileContents.split("\n");
 
-  for (const line of lines) {
-    // Skip commented lines
-    if (line.trim().startsWith("#")) {
-      continue;
+  const version = stripVersionPrefix(versions[0]);
+  if (isPath(version)) {
+    core.warning(
+      `The uv version ${versions[0]} in .tool-versions is not supported. Paths are not allowed.`,
+    );
+    return undefined;
   }
-    const match = line.match(/^\s*uv\s*v?\s*(?<version>[^\s]+)\s*$/);
-    if (match) {
-      const matchedVersion = match.groups?.version.trim();
-      if (matchedVersion?.startsWith("ref")) {
+  if (version.startsWith("ref")) {
     core.warning(
       "The ref syntax of .tool-versions is not supported. Please use a released version instead.",
     );
     return undefined;
   }
-      return matchedVersion;
+  return version;
+}
+
+export function getPythonVersionFromToolVersions(
+  filePath: string,
+): string | undefined {
+  const versions = getToolVersions(filePath, "python");
+  if (versions === undefined || versions.length === 0) {
+    return undefined;
+  }
+  if (versions.length > 1) {
+    core.warning(
+      "Multiple Python versions in .tool-versions are not supported. The Python entry will be ignored.",
+    );
+    return undefined;
+  }
+
+  const version = stripVersionPrefix(versions[0]);
+  if (
+    version === "system" ||
+    version.startsWith("ref:") ||
+    version.startsWith("path:") ||
+    isPath(version)
+  ) {
+    core.warning(
+      `The Python version ${versions[0]} in .tool-versions is not supported. The Python entry will be ignored.`,
+    );
+    return undefined;
+  }
+  return version;
+}
+
+function getToolVersions(
+  filePath: string,
+  toolName: string,
+): string[] | undefined {
+  if (!filePath.endsWith(".tool-versions")) {
+    return undefined;
+  }
+  const fileContents = fs.readFileSync(filePath, "utf8");
+
+  for (const line of fileContents.split("\n")) {
+    const content = line.split("#", 1)[0].trim();
+    if (content === "") {
+      continue;
+    }
+
+    const [tool, ...versions] = content.split(/\s+/);
+    if (tool === toolName) {
+      return versions;
     }
   }
   return undefined;
 }
+
+function stripVersionPrefix(version: string): string {
+  return version.startsWith("v") ? version.slice(1) : version;
+}
+
+function isPath(version: string): boolean {
+  return version.includes("/") || version.includes("\\");
+}

tsconfig.json

@@ -5,6 +5,7 @@
     "module": "esnext",
     "moduleResolution": "bundler",
     "noImplicitAny": true,
+    "resolveJsonModule": true,
     "strict": true,
     "target": "ES2022"
   },