Add a Python architecture input

chore: update known checksums for 0.12.20

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

.github/workflows/test.yml

@@ -27,7 +27,7 @@ jobs:
       - name: Actionlint
         uses: eifinger/actionlint-action@1fc89649be682d16ec5cf65ea16e269eb88d3982 # v1.10.2
       - name: Run zizmor
-        uses: zizmorcore/zizmor-action@3dc1ecc9bcb9e94e9b2c709687979e1298497054 # v0.6.2
+        uses: zizmorcore/zizmor-action@70fb788f84895a7701f5643d103d587e460b5c99 # v0.6.3
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: .nvmrc

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)
@@ -56,6 +57,9 @@ Have a look under [Advanced Configuration](#advanced-configuration) for detailed
     # 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"
 
@@ -193,6 +197,25 @@ jobs:
         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.

__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", () => {
@@ -71,4 +94,39 @@ describe("restoreCache", () => {
       "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__/helpers/setup-inputs.ts

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

__tests__/utils/inputs.test.ts

@@ -19,6 +19,7 @@ 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();
@@ -37,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-"));
@@ -62,6 +65,7 @@ function resetEnvironment(): void {
   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;
 }
 
@@ -77,6 +81,11 @@ function restoreEnvironment(): void {
   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;
 }
 
@@ -98,6 +107,7 @@ 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");
@@ -149,6 +159,28 @@ describe("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) => {

__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();
+  });
+});

action-types.yml

@@ -7,6 +7,8 @@ inputs:
     type: string
   python-version:
     type: string
+  python-arch:
+    type: string
   activate-environment:
     type: boolean
   venv-path:

action.yml

@@ -12,6 +12,9 @@ inputs:
   python-version:
     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. "
     default: "false"

dist/save-cache/index.cjs

@@ -63714,15 +63714,6 @@ function info2(msg) {
 }
 var warning2 = warning;
 
-// src/cache/restore-cache.ts
-var STATE_CACHE_KEY = "cache-key";
-var STATE_CACHE_MATCHED_KEY = "cache-matched-key";
-var STATE_PYTHON_CACHE_MATCHED_KEY = "python-cache-matched-key";
-
-// src/utils/constants.ts
-var STATE_UV_PATH = "uv-path";
-var STATE_UV_VERSION = "uv-version";
-
 // src/utils/inputs.ts
 var import_node_fs4 = __toESM(require("node:fs"), 1);
 var import_node_path = __toESM(require("node:path"), 1);
@@ -64447,6 +64438,7 @@ function loadInputs() {
   const version3 = getInput("version");
   const versionFile = getVersionFile(workingDirectory);
   const pythonVersion = getPythonVersion(versionFile);
+  const pythonArch = getInput("python-arch");
   const activateEnvironment = getBooleanInput("activate-environment");
   const noProject = getBooleanInput("no-project");
   const venvPath = getVenvPath(workingDirectory, activateEnvironment);
@@ -64490,6 +64482,7 @@ function loadInputs() {
     manifestFile,
     noProject,
     pruneCache: pruneCache2,
+    pythonArch,
     pythonDir,
     pythonVersion,
     quiet: quiet2,
@@ -64738,6 +64731,15 @@ function getResolutionStrategy() {
   );
 }
 
+// src/cache/restore-cache.ts
+var STATE_CACHE_KEY = "cache-key";
+var STATE_CACHE_MATCHED_KEY = "cache-matched-key";
+var STATE_PYTHON_CACHE_MATCHED_KEY = "python-cache-matched-key";
+
+// src/utils/constants.ts
+var STATE_UV_PATH = "uv-path";
+var STATE_UV_VERSION = "uv-version";
+
 // src/save-cache.ts
 function formatUnexpectedFailure(error2) {
   if (error2 instanceof Error) {

dist/update-known-checksums/index.cjs

@@ -47182,6 +47182,60 @@ var semver = __toESM(require_semver(), 1);
 
 // src/download/checksum/known-checksums.json
 var known_checksums_default = {
+  "aarch64-apple-darwin-0.12.20": "848fdeb602ff1a1baacd4f6c8b7bdc6cf1ad026a6d9cf59475fda17c179743ca",
+  "aarch64-pc-windows-msvc-0.12.20": "b6bd9218855591742ffd3b00fcf2044b4d2fb6446b6a3545e0dfee447e950388",
+  "aarch64-unknown-linux-gnu-0.12.20": "8a7aad7bc76a2fae5151566ff3e43eacce0b2a113d5e4de3e4afe3e58fa2441e",
+  "aarch64-unknown-linux-musl-0.12.20": "94bb13feeebc6b59a4124016c957cdc9ee406d1476ce2b2ce2991e95b8e820b7",
+  "arm-unknown-linux-musleabihf-0.12.20": "6aeef64cf07b43135d6b1c20bd57809f2d965d0f8a2d5602230d5d55b8245477",
+  "armv7-unknown-linux-gnueabihf-0.12.20": "e1c53318608448ad3b8e7f2e9b069936730a6e7b47831ba5446e4b4f436ee715",
+  "armv7-unknown-linux-musleabihf-0.12.20": "a4c3a0e12e5489f092c93b232ddc4a811a6ea9a03f447f91f88e96867c0bac8d",
+  "i686-pc-windows-msvc-0.12.20": "1a372c273370ae9a7e9aa84020ce91fc1d9ebecbd287c3447e7e99cada0b14f3",
+  "i686-unknown-linux-gnu-0.12.20": "f1e83cc88970ed799b507a8392152d19916dfa0b6c9ae9c8145742035a40d5cb",
+  "i686-unknown-linux-musl-0.12.20": "11d541dd32dd779adbdfef69fe30d7d325036f50d394d3f260a0042998e05499",
+  "powerpc64le-unknown-linux-gnu-0.12.20": "39224a5bfc21a8041afc0315e5d47c86acecf4e669944564950996b516fb5987",
+  "riscv64gc-unknown-linux-gnu-0.12.20": "5cb9df36ca64fb72673c59a77b955b50f3bb907689a98d1d8d640aa3e71f2660",
+  "riscv64gc-unknown-linux-musl-0.12.20": "360e91a317a27bd33978577c57b6f3ed778bdfe8c30c9b613e46fdc33bf8aee8",
+  "s390x-unknown-linux-gnu-0.12.20": "25485439b52cb029afa724c442418ca08a53122100f8cce68ccceb88323ccde2",
+  "x86_64-apple-darwin-0.12.20": "ac54283d211fd77cdc152b67606dbaf6406ff4ab03f3af4ae99468fa8e887141",
+  "x86_64-pc-windows-msvc-0.12.20": "95f9bc30fbb3574d276e28ac4a6de932d25153645853d13da8c21eec3bc88d06",
+  "x86_64-unknown-linux-gnu-0.12.20": "6590717592ace991ff83a63fef799e3ad9d33ecc8f96c5d6bdd732496e79337f",
+  "x86_64-unknown-linux-musl-0.12.20": "14114d66a094f1907af0fcbc863f34226bbb7f5e430e13dce6676ba40dcc6891",
+  "aarch64-apple-darwin-0.12.19": "a9a8df1eedeb192f2e47e40e2faabfb387db4b850209118786d42f89dde3e0ba",
+  "aarch64-pc-windows-msvc-0.12.19": "115b54cb823bc48260670f5782001add6067ac8d98d18c8263a833704e287de9",
+  "aarch64-unknown-linux-gnu-0.12.19": "0804e9b164c64b6914182d5920c08551958a095986f10a3731056df701126436",
+  "aarch64-unknown-linux-musl-0.12.19": "ad8d8448a2ff642ba62c2f684d7dd22a03f8eb3fc9918c2c3e8ec975f4ed6710",
+  "arm-unknown-linux-musleabihf-0.12.19": "173b6b118e444dc3b3a0b6337dd87d66fa79835aa5e059d79e942ae33a850e20",
+  "armv7-unknown-linux-gnueabihf-0.12.19": "f47fe74244c4adcff20637c1aee2550dbc31c81ccf0b2a9537bf98b24bc4028a",
+  "armv7-unknown-linux-musleabihf-0.12.19": "0df353aac087509c47fe660837ca5d284858ef4a5eec4042cbcdeb0118ba0f1b",
+  "i686-pc-windows-msvc-0.12.19": "e1c2d19d1173a0e9f81ba3f95881ad741808133e372610889ff6870629218c7f",
+  "i686-unknown-linux-gnu-0.12.19": "952b0bae707e19b2b5d012b46519a2159be929273d466a1437759f0961be0b93",
+  "i686-unknown-linux-musl-0.12.19": "f923ac32e0e5139950fe1b63abab74d48cabb94b15c90637bc380dadcaf4da40",
+  "powerpc64le-unknown-linux-gnu-0.12.19": "e30649ad846a14bd96440efd45fdb60dcdf8db088fb143064aa78632048ad957",
+  "riscv64gc-unknown-linux-gnu-0.12.19": "50a83ea999ea861a6a853ae1ad0982baad96cc6451e46a5d7e366c4d9475f1bb",
+  "riscv64gc-unknown-linux-musl-0.12.19": "051de9eda7e09dab4c8a304ab2e119317649fee0e24efd0358f410d0c5b3407f",
+  "s390x-unknown-linux-gnu-0.12.19": "e6a9149ea122c1b3b9719ca3577c321376e3c400e004c3cc18231fdb1d35107b",
+  "x86_64-apple-darwin-0.12.19": "cb5fa57bafe68fc0fb94b17f06bee0b0b9a7feb94ccbd110445afa0696e39273",
+  "x86_64-pc-windows-msvc-0.12.19": "6dbb02d79e419522f1c500f0adb1cddcff0cda7d59b0d66ea7f5e3b4a1b2f5f0",
+  "x86_64-unknown-linux-gnu-0.12.19": "23bf5552d220e0842b65c862097b2ebaeba0064b74eda5e565e77fd25969d8c8",
+  "x86_64-unknown-linux-musl-0.12.19": "db7278c9f57981338fddff1fb250e11964bc0a4fafcb9eed8303fdb117dc067b",
+  "aarch64-apple-darwin-0.12.18": "cf40e0c6a202190ccd9e0406dcfdd5b2d6668a9a5c779b17948963df32aafe5b",
+  "aarch64-pc-windows-msvc-0.12.18": "17f27b1c64eacc757ae603579f116a014881e486c5e79ae81877980d4699e943",
+  "aarch64-unknown-linux-gnu-0.12.18": "afb6291f3f0a6b4521fc67b947822506c41dde5b60d2189dd8f3695b2ac8c9e7",
+  "aarch64-unknown-linux-musl-0.12.18": "0796973fb3eea8095078c3d0659bd17a5f6789a71b8dd85caff2483178f78ac3",
+  "arm-unknown-linux-musleabihf-0.12.18": "a37127fb331d5e6228efc1f8549d2447b50c907eee4629347f150a649083619c",
+  "armv7-unknown-linux-gnueabihf-0.12.18": "a38e82350e1e95d5526d1ab81d9b4eb676815c51646243b3b3fbc55b218732d1",
+  "armv7-unknown-linux-musleabihf-0.12.18": "41f0808328f65910bacdb487638475715f949900c7a23b393b3754e2156ff15a",
+  "i686-pc-windows-msvc-0.12.18": "e04c0f1fd9a8703761f9edd64d797ddb2c9a3e6eec0e2fed234a7bd2c2e868b9",
+  "i686-unknown-linux-gnu-0.12.18": "278dbc5dfc6bdde33a553fdba53174cc49daf512a857db1b3c1b5d663290196f",
+  "i686-unknown-linux-musl-0.12.18": "ebfdaaafc447fb2a7329cde879a7748b2ab40ecdcd3d5f04fc0a5d1ab79bb0bd",
+  "powerpc64le-unknown-linux-gnu-0.12.18": "332d174248230ed599a9df0e4e77d6921dbb42ca0fdfbe26eb2a6c999da936b3",
+  "riscv64gc-unknown-linux-gnu-0.12.18": "be88652a03225acbd6bf7204d006b244b0743c8c756a35137c209fa4ff731c41",
+  "riscv64gc-unknown-linux-musl-0.12.18": "29d34dcc833b99b09f78fa11c66fa3c490c3e37c4f0d754e7b84f7147850190e",
+  "s390x-unknown-linux-gnu-0.12.18": "ac412f7ab2a096a7302e0ae8828c7ef84db8a1f7ff97acba8ff8987d46d39cec",
+  "x86_64-apple-darwin-0.12.18": "2e4108f5395397c8bc5d43bf83d3bdbb2d0e92b90d0efa607756be704905fa33",
+  "x86_64-pc-windows-msvc-0.12.18": "cae6a3bc25239f83dffb467a4b180508d9da23986c04639ebfa44e43e6a84bff",
+  "x86_64-unknown-linux-gnu-0.12.18": "89eadd7c76fc063887959510d5ba0ab1264dfd5f1143b925ddb73021a40acf16",
+  "x86_64-unknown-linux-musl-0.12.18": "e38d97460b98ebfd31b197de0fe9fa578add4bc8ba0179b203dd3f87b99f98e6",
   "aarch64-apple-darwin-0.12.17": "85f00cbdc6dd3e97eba4c31b4d014375a9fdfe8f570023b84e5102fc3456896b",
   "aarch64-pc-windows-msvc-0.12.17": "3e1aa6849d77f0e00dc865e4afab5c5b32de053e21fe35bf5ad5cec3734ec976",
   "aarch64-unknown-linux-gnu-0.12.17": "d636d1b678e9e7f367ecb22b46bd1cabbed234d6bc3b4d96365d2b507f72f86c",

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

docs/environment-and-tools.md

@@ -144,6 +144,7 @@ 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` 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.
@@ -155,6 +156,7 @@ 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

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/known-checksums.json

@@ -1,4 +1,58 @@
 {
+  "aarch64-apple-darwin-0.12.20": "848fdeb602ff1a1baacd4f6c8b7bdc6cf1ad026a6d9cf59475fda17c179743ca",
+  "aarch64-pc-windows-msvc-0.12.20": "b6bd9218855591742ffd3b00fcf2044b4d2fb6446b6a3545e0dfee447e950388",
+  "aarch64-unknown-linux-gnu-0.12.20": "8a7aad7bc76a2fae5151566ff3e43eacce0b2a113d5e4de3e4afe3e58fa2441e",
+  "aarch64-unknown-linux-musl-0.12.20": "94bb13feeebc6b59a4124016c957cdc9ee406d1476ce2b2ce2991e95b8e820b7",
+  "arm-unknown-linux-musleabihf-0.12.20": "6aeef64cf07b43135d6b1c20bd57809f2d965d0f8a2d5602230d5d55b8245477",
+  "armv7-unknown-linux-gnueabihf-0.12.20": "e1c53318608448ad3b8e7f2e9b069936730a6e7b47831ba5446e4b4f436ee715",
+  "armv7-unknown-linux-musleabihf-0.12.20": "a4c3a0e12e5489f092c93b232ddc4a811a6ea9a03f447f91f88e96867c0bac8d",
+  "i686-pc-windows-msvc-0.12.20": "1a372c273370ae9a7e9aa84020ce91fc1d9ebecbd287c3447e7e99cada0b14f3",
+  "i686-unknown-linux-gnu-0.12.20": "f1e83cc88970ed799b507a8392152d19916dfa0b6c9ae9c8145742035a40d5cb",
+  "i686-unknown-linux-musl-0.12.20": "11d541dd32dd779adbdfef69fe30d7d325036f50d394d3f260a0042998e05499",
+  "powerpc64le-unknown-linux-gnu-0.12.20": "39224a5bfc21a8041afc0315e5d47c86acecf4e669944564950996b516fb5987",
+  "riscv64gc-unknown-linux-gnu-0.12.20": "5cb9df36ca64fb72673c59a77b955b50f3bb907689a98d1d8d640aa3e71f2660",
+  "riscv64gc-unknown-linux-musl-0.12.20": "360e91a317a27bd33978577c57b6f3ed778bdfe8c30c9b613e46fdc33bf8aee8",
+  "s390x-unknown-linux-gnu-0.12.20": "25485439b52cb029afa724c442418ca08a53122100f8cce68ccceb88323ccde2",
+  "x86_64-apple-darwin-0.12.20": "ac54283d211fd77cdc152b67606dbaf6406ff4ab03f3af4ae99468fa8e887141",
+  "x86_64-pc-windows-msvc-0.12.20": "95f9bc30fbb3574d276e28ac4a6de932d25153645853d13da8c21eec3bc88d06",
+  "x86_64-unknown-linux-gnu-0.12.20": "6590717592ace991ff83a63fef799e3ad9d33ecc8f96c5d6bdd732496e79337f",
+  "x86_64-unknown-linux-musl-0.12.20": "14114d66a094f1907af0fcbc863f34226bbb7f5e430e13dce6676ba40dcc6891",
+  "aarch64-apple-darwin-0.12.19": "a9a8df1eedeb192f2e47e40e2faabfb387db4b850209118786d42f89dde3e0ba",
+  "aarch64-pc-windows-msvc-0.12.19": "115b54cb823bc48260670f5782001add6067ac8d98d18c8263a833704e287de9",
+  "aarch64-unknown-linux-gnu-0.12.19": "0804e9b164c64b6914182d5920c08551958a095986f10a3731056df701126436",
+  "aarch64-unknown-linux-musl-0.12.19": "ad8d8448a2ff642ba62c2f684d7dd22a03f8eb3fc9918c2c3e8ec975f4ed6710",
+  "arm-unknown-linux-musleabihf-0.12.19": "173b6b118e444dc3b3a0b6337dd87d66fa79835aa5e059d79e942ae33a850e20",
+  "armv7-unknown-linux-gnueabihf-0.12.19": "f47fe74244c4adcff20637c1aee2550dbc31c81ccf0b2a9537bf98b24bc4028a",
+  "armv7-unknown-linux-musleabihf-0.12.19": "0df353aac087509c47fe660837ca5d284858ef4a5eec4042cbcdeb0118ba0f1b",
+  "i686-pc-windows-msvc-0.12.19": "e1c2d19d1173a0e9f81ba3f95881ad741808133e372610889ff6870629218c7f",
+  "i686-unknown-linux-gnu-0.12.19": "952b0bae707e19b2b5d012b46519a2159be929273d466a1437759f0961be0b93",
+  "i686-unknown-linux-musl-0.12.19": "f923ac32e0e5139950fe1b63abab74d48cabb94b15c90637bc380dadcaf4da40",
+  "powerpc64le-unknown-linux-gnu-0.12.19": "e30649ad846a14bd96440efd45fdb60dcdf8db088fb143064aa78632048ad957",
+  "riscv64gc-unknown-linux-gnu-0.12.19": "50a83ea999ea861a6a853ae1ad0982baad96cc6451e46a5d7e366c4d9475f1bb",
+  "riscv64gc-unknown-linux-musl-0.12.19": "051de9eda7e09dab4c8a304ab2e119317649fee0e24efd0358f410d0c5b3407f",
+  "s390x-unknown-linux-gnu-0.12.19": "e6a9149ea122c1b3b9719ca3577c321376e3c400e004c3cc18231fdb1d35107b",
+  "x86_64-apple-darwin-0.12.19": "cb5fa57bafe68fc0fb94b17f06bee0b0b9a7feb94ccbd110445afa0696e39273",
+  "x86_64-pc-windows-msvc-0.12.19": "6dbb02d79e419522f1c500f0adb1cddcff0cda7d59b0d66ea7f5e3b4a1b2f5f0",
+  "x86_64-unknown-linux-gnu-0.12.19": "23bf5552d220e0842b65c862097b2ebaeba0064b74eda5e565e77fd25969d8c8",
+  "x86_64-unknown-linux-musl-0.12.19": "db7278c9f57981338fddff1fb250e11964bc0a4fafcb9eed8303fdb117dc067b",
+  "aarch64-apple-darwin-0.12.18": "cf40e0c6a202190ccd9e0406dcfdd5b2d6668a9a5c779b17948963df32aafe5b",
+  "aarch64-pc-windows-msvc-0.12.18": "17f27b1c64eacc757ae603579f116a014881e486c5e79ae81877980d4699e943",
+  "aarch64-unknown-linux-gnu-0.12.18": "afb6291f3f0a6b4521fc67b947822506c41dde5b60d2189dd8f3695b2ac8c9e7",
+  "aarch64-unknown-linux-musl-0.12.18": "0796973fb3eea8095078c3d0659bd17a5f6789a71b8dd85caff2483178f78ac3",
+  "arm-unknown-linux-musleabihf-0.12.18": "a37127fb331d5e6228efc1f8549d2447b50c907eee4629347f150a649083619c",
+  "armv7-unknown-linux-gnueabihf-0.12.18": "a38e82350e1e95d5526d1ab81d9b4eb676815c51646243b3b3fbc55b218732d1",
+  "armv7-unknown-linux-musleabihf-0.12.18": "41f0808328f65910bacdb487638475715f949900c7a23b393b3754e2156ff15a",
+  "i686-pc-windows-msvc-0.12.18": "e04c0f1fd9a8703761f9edd64d797ddb2c9a3e6eec0e2fed234a7bd2c2e868b9",
+  "i686-unknown-linux-gnu-0.12.18": "278dbc5dfc6bdde33a553fdba53174cc49daf512a857db1b3c1b5d663290196f",
+  "i686-unknown-linux-musl-0.12.18": "ebfdaaafc447fb2a7329cde879a7748b2ab40ecdcd3d5f04fc0a5d1ab79bb0bd",
+  "powerpc64le-unknown-linux-gnu-0.12.18": "332d174248230ed599a9df0e4e77d6921dbb42ca0fdfbe26eb2a6c999da936b3",
+  "riscv64gc-unknown-linux-gnu-0.12.18": "be88652a03225acbd6bf7204d006b244b0743c8c756a35137c209fa4ff731c41",
+  "riscv64gc-unknown-linux-musl-0.12.18": "29d34dcc833b99b09f78fa11c66fa3c490c3e37c4f0d754e7b84f7147850190e",
+  "s390x-unknown-linux-gnu-0.12.18": "ac412f7ab2a096a7302e0ae8828c7ef84db8a1f7ff97acba8ff8987d46d39cec",
+  "x86_64-apple-darwin-0.12.18": "2e4108f5395397c8bc5d43bf83d3bdbb2d0e92b90d0efa607756be704905fa33",
+  "x86_64-pc-windows-msvc-0.12.18": "cae6a3bc25239f83dffb467a4b180508d9da23986c04639ebfa44e43e6a84bff",
+  "x86_64-unknown-linux-gnu-0.12.18": "89eadd7c76fc063887959510d5ba0ab1264dfd5f1143b925ddb73021a40acf16",
+  "x86_64-unknown-linux-musl-0.12.18": "e38d97460b98ebfd31b197de0fe9fa578add4bc8ba0179b203dd3f87b99f98e6",
   "aarch64-apple-darwin-0.12.17": "85f00cbdc6dd3e97eba4c31b4d014375a9fdfe8f570023b84e5102fc3456896b",
   "aarch64-pc-windows-msvc-0.12.17": "3e1aa6849d77f0e00dc865e4afab5c5b32de053e21fe35bf5ad5cec3734ec976",
   "aarch64-unknown-linux-gnu-0.12.17": "d636d1b678e9e7f367ecb22b46bd1cabbed234d6bc3b4d96365d2b507f72f86c",

src/setup-uv.ts

@@ -16,6 +16,7 @@ import {
   getPlatform,
   type Platform,
 } from "./utils/platforms";
+import { setupPythonArch } from "./utils/python-arch";
 import { getPythonRuntimeId } from "./utils/python-runtime";
 import { resolveUvVersion } from "./version/resolve";
 
@@ -86,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);

src/utils/inputs.ts

@@ -24,6 +24,7 @@ export interface SetupInputs {
   version: string;
   versionFile: string;
   pythonVersion: string;
+  pythonArch: string;
   activateEnvironment: boolean;
   noProject: boolean;
   venvPath: string;
@@ -54,6 +55,7 @@ export function loadInputs(): SetupInputs {
   const version = core.getInput("version");
   const versionFile = getVersionFile(workingDirectory);
   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);
@@ -100,6 +102,7 @@ export function loadInputs(): SetupInputs {
     manifestFile,
     noProject,
     pruneCache,
+    pythonArch,
     pythonDir,
     pythonVersion,
     quiet,
@@ -146,6 +149,10 @@ function getPythonVersion(versionFile: string): string {
   }
 }
 
+export function resolvePythonArch(pythonArch: string): string {
+  return pythonArch || process.env.UV_PYTHON_ARCH || "";
+}
+
 function getVenvPath(
   workingDirectory: string,
   activateEnvironment: boolean,

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;
+  }
+}