feat: fall back to system Python when pre-built binaries unavailable by gounthar · Pull Request #1289 · actions/setup-python

gounthar · 2026-03-18T14:48:28Z

Summary

When pre-built Python binaries are not available for the current architecture, fall back to system Python instead of failing with an error.

This enables setup-python to work on architectures like riscv64 that don't yet have pre-built binaries in actions/python-versions. RISC-V self-hosted runners are becoming available through programs like RISE RISC-V runners, used by numpy, llama.cpp, and pytorch.

Changes

src/find-python.ts: Before throwing "version not found" error, check if system python3 exists and satisfies the requested version spec. If so, use it and emit a warning.

Behavior

No change for architectures with pre-built binaries (x86_64, arm64, etc.)
On unsupported architectures (riscv64, etc.): uses system Python if version matches, warns user
Still fails if system Python doesn't satisfy the version spec

Test plan

Builds successfully (npm run build)
Verify on riscv64 self-hosted runner with system Python 3.12

Fixes #1288

When pre-built Python binaries are not available for the current architecture (e.g., riscv64), try using system Python as a fallback instead of failing with an error. This enables setup-python to work on architectures that don't yet have pre-built binaries in actions/python-versions, such as riscv64 self-hosted runners. The fallback only activates when: 1. No cached version is found 2. No manifest entry exists for the architecture 3. System python3 exists and satisfies the requested version spec A warning is emitted so users know the fallback was used. Fixes actions#1288 Signed-off-by: Bruno Verachten <gounthar@gmail.com>

Copilot

Pull request overview

This PR adds a fallback path in actions/setup-python so that when no pre-built CPython binary can be found for the requested version/architecture, the action can optionally use a compatible system python3 instead of failing (targeting unsupported architectures like riscv64).

Changes:

Add system python3 fallback resolution in useCpythonVersion when toolcache + manifest lookup fails.
Emit a warning when falling back to system Python.
Update the bundled dist output to include the same logic.

Reviewed changes

Copilot reviewed 1 out of 2 changed files in this pull request and generated 4 comments.

File	Description
src/find-python.ts	Adds system `python3` fallback when no cached/downloadable CPython is found.
dist/setup/index.js	Compiled distribution output reflecting the new fallback behavior.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

gounthar · 2026-03-19T13:33:56Z

src/find-python.ts

+  if (!installDir) {
+    // Try system Python as fallback (e.g., on architectures without pre-built binaries)
+    try {
+      const {exitCode, stdout} = await exec.getExecOutput('python3', [
+        '-c',
+        'import sys; print(sys.prefix)'
+      ]);
+      if (exitCode === 0) {
+        const systemPrefix = stdout.trim();
+        const systemVersion = await exec.getExecOutput('python3', [
+          '-c',
+          'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")'
+        ]);
+        if (
+          systemVersion.exitCode === 0 &&
+          semver.satisfies(systemVersion.stdout.trim(), semanticVersionSpec)
+        ) {
+          installDir = systemPrefix;
+          core.warning(
+            `Pre-built Python not available for architecture '${architecture}'. Using system Python ${systemVersion.stdout.trim()} at ${systemPrefix}.`
+          );
+        }
+      }
+    } catch {
+      // System Python not available, fall through to error
+    }
+  }


Addressed — tests will be added in a follow-up. The structural fixes in this push are the priority.

gounthar · 2026-03-19T13:33:58Z

src/find-python.ts

+  if (!installDir) {
+    // Try system Python as fallback (e.g., on architectures without pre-built binaries)
+    try {
+      const {exitCode, stdout} = await exec.getExecOutput('python3', [
+        '-c',
+        'import sys; print(sys.prefix)'
+      ]);
+      if (exitCode === 0) {
+        const systemPrefix = stdout.trim();
+        const systemVersion = await exec.getExecOutput('python3', [
+          '-c',
+          'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")'
+        ]);
+        if (
+          systemVersion.exitCode === 0 &&
+          semver.satisfies(systemVersion.stdout.trim(), semanticVersionSpec)
+        ) {
+          installDir = systemPrefix;
+          core.warning(
+            `Pre-built Python not available for architecture '${architecture}'. Using system Python ${systemVersion.stdout.trim()} at ${systemPrefix}.`
+          );
+        }


Fixed — added !freethreaded guard. The fallback is now skipped entirely for free-threaded builds.

gounthar · 2026-03-19T13:34:00Z

src/find-python.ts

+        'import sys; print(sys.prefix)'
+      ]);
+      if (exitCode === 0) {
+        const systemPrefix = stdout.trim();
+        const systemVersion = await exec.getExecOutput('python3', [
+          '-c',
+          'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")'
+        ]);
+        if (
+          systemVersion.exitCode === 0 &&
+          semver.satisfies(systemVersion.stdout.trim(), semanticVersionSpec)
+        ) {
+          installDir = systemPrefix;
+          core.warning(
+            `Pre-built Python not available for architecture '${architecture}'. Using system Python ${systemVersion.stdout.trim()} at ${systemPrefix}.`


Fixed — the fallback now returns early with outputs captured directly from sys.executable, sys.prefix, and os.path.dirname(sys.executable). No longer sets installDir or relies on versionFromPath()/binDir().

gounthar · 2026-03-19T13:34:01Z

src/find-python.ts

+  if (!installDir) {
+    // Try system Python as fallback (e.g., on architectures without pre-built binaries)
+    try {
+      const {exitCode, stdout} = await exec.getExecOutput('python3', [
+        '-c',
+        'import sys; print(sys.prefix)'
+      ]);
+      if (exitCode === 0) {
+        const systemPrefix = stdout.trim();
+        const systemVersion = await exec.getExecOutput('python3', [
+          '-c',
+          'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")'
+        ]);
+        if (
+          systemVersion.exitCode === 0 &&
+          semver.satisfies(systemVersion.stdout.trim(), semanticVersionSpec)
+        ) {
+          installDir = systemPrefix;
+          core.warning(
+            `Pre-built Python not available for architecture '${architecture}'. Using system Python ${systemVersion.stdout.trim()} at ${systemPrefix}.`
+          );
+        }
+      }
+    } catch {
+      // System Python not available, fall through to error
+    }
+  }


Fixed — the fallback now only triggers when the manifest has zero entries for the current architecture (!archHasManifestEntries). On x86_64/arm64 where the manifest has entries, the original error behavior is preserved.

- Gate fallback on architecture having no manifest entries, preventing false triggers on supported architectures with missing versions - Skip fallback for free-threaded Python builds - Return early with correct outputs (sys.executable, version, bin dir) instead of relying on toolcache path parsing which breaks with system prefix paths like /usr - Set environment variables (pythonLocation, Python_ROOT_DIR, etc.) correctly for system Python paths Signed-off-by: Bruno Verachten <gounthar@gmail.com>

gounthar · 2026-03-19T13:31:41Z

Pushed a v2 addressing all review feedback:

Path parsing fix: The fallback now captures sys.executable, version, prefix, and bin dir directly from the system Python, no longer relies on versionFromPath() which expects toolcache layout. Returns early with correct outputs.
Scope narrowing: The fallback only triggers when the manifest has no entries at all for the current architecture. If the manifest has entries for the arch (e.g., x86_64) but the specific version isn't found, it fails normally. This prevents silent fallback on supported platforms.
Free-threaded skip: Added !freethreaded guard; the fallback is skipped entirely for free-threaded builds since we can't verify the system Python is a free-threaded build.
Tests: will add in a follow-up if this approach is acceptable to the maintainers.

Signed-off-by: Bruno Verachten <gounthar@gmail.com>

gounthar · 2026-03-19T13:45:53Z

Tests added in cb5cf22: 5 new test cases covering the system Python fallback:

Happy path: falls back to system Python on unsupported architecture (riscv64)
Scope guard: does NOT fall back on supported architecture (x64) with missing version
Version mismatch: does NOT fall back when system Python doesn't satisfy the version spec
Free-threaded guard: does NOT fall back for free-threaded builds
Missing python3: handles gracefully when system Python is not available

All 13 tests pass (8 existing + 5 new).

weiji14 · 2026-03-30T08:53:26Z

dist/setup/index.js

+            try {
+                const sysInfo = await exec.getExecOutput('python3', [
+                    '-c',
+                    'import sys, os; print(sys.executable + "\\n" + f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}" + "\\n" + sys.prefix + "\\n" + os.path.dirname(sys.executable))'
+                ]);
+                if (sysInfo.exitCode === 0) {
+                    const [sysExecutable, sysVersion, sysPrefix, sysBinDir] = sysInfo.stdout.trim().split('\n');
+                    if (semver.satisfies(sysVersion, semanticVersionSpec)) {
+                        core.warning(`Pre-built Python not available for architecture '${baseArchitecture}'. Using system Python ${sysVersion} at ${sysExecutable}.`);


Is this somewhat hardcoded to whatever the default Python version on the runner image is at the moment? I.e. Python 3.12 on the ubuntu-24.04-riscv images? I was testing this branch out using python-version: "3.13" at weiji14/cog3pio@c40e8af, but got the following error output:

Run gounthar/setup-python@cb5cf223af5f1712fe2914b9c669d2008e051022 Installed versions Version 3.13 was not found in the local cache /usr/bin/python3 -c import sys, os; print(sys.executable + "\n" + f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}" + "\n" + sys.prefix + "\n" + os.path.dirname(sys.executable)) /usr/bin/python3 3.12.13 /opt/python-3.12 /usr/bin Error: The version '3.13' with architecture 'riscv64' was not found for Ubuntu 24.04. The list of all available versions can be found here: https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json 0s

If I change to using python-version: "3.x" (see this commit), it picks up Python 3.12:

Version 3.x was not found in the local cache /usr/bin/python3 -c import sys, os; print(sys.executable + "\n" + f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}" + "\n" + sys.prefix + "\n" + os.path.dirname(sys.executable)) /usr/bin/python3 3.12.13 /opt/python-3.12 /usr/bin Warning: Pre-built Python not available for architecture 'riscv64'. Using system Python 3.12.13 at /usr/bin/python3. Successfully set up CPython (3.12.13)

but I hit into another error with PyO3/maturin-action (which is a separate issue 🙂). I'm wondering how much effort it would be to allow a different Python version?

gounthar · 2026-03-30T08:58:36Z

Thanks for testing this. You are right that it only picks up whatever Python version is on the runner. The RISE runner currently ships 3.12 only, so requesting 3.13 fails.

The fallback checks whether the system Python satisfies the requested version spec and bails out if it does not, which is why 3.13 gives the original error while 3.x works.

Supporting multiple versions would require the RISE runner image to pre-install them (like the standard ubuntu-24.04 runners do with 3.9-3.13 in the toolcache). I have mentioned this to the RISE team but not sure when it will happen.

For now, python-version: "3.x" or python-version: "3.12" are the reliable options on riscv64.

weiji14 · 2026-03-30T09:08:43Z

Supporting multiple versions would require the RISE runner image to pre-install them (like the standard ubuntu-24.04 runners do with 3.9-3.13 in the toolcache). I have mentioned this to the RISE team but not sure when it will happen.

I did see Python 3.13 in this Dockerfile (https://github.com/riseproject-dev/riscv-runner-images/blame/598f920e51bba243f1f3f75efa2e98f6c7eb9a0c/runner/Dockerfile.ubuntu#L158-L182), as well as 3.10-3.14 and 3.13t/3.14t, but maybe I'm not looking at the correct place?

gounthar · 2026-03-30T09:24:30Z

Good find. The Dockerfile does install Python 3.10-3.14 in /opt/python-3.x/. I did not check those carefully enough. When I tried using them on the actual runner, they were missing standard library modules (e.g. math), which broke venv and most tools. That is why the fallback ended up using system Python instead.

I reported the broken /opt/python issue to the RISE team (riseproject-dev/riscv-runner-images#21). Once those installations work properly, the fallback should look there for the requested version instead of only checking system Python.

gounthar requested a review from a team as a code owner March 18, 2026 14:48

Copilot AI review requested due to automatic review settings March 18, 2026 14:48

Copilot started reviewing on behalf of gounthar March 18, 2026 14:49 View session

Copilot AI reviewed Mar 18, 2026

View reviewed changes

This was referenced Mar 18, 2026

ci: add riscv64 native wheel build using RISE runners riseproject-dev/numpy#1

Open

Epic: upstream riscv64 wheel support to all 33 packages gounthar/riscv64-python-wheels#15

Open

test: add 5 tests for system Python fallback

cb5cf22

Signed-off-by: Bruno Verachten <gounthar@gmail.com>

weiji14 reviewed Mar 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: fall back to system Python when pre-built binaries unavailable#1289

feat: fall back to system Python when pre-built binaries unavailable#1289
gounthar wants to merge 3 commits intoactions:mainfrom
gounthar:feat/system-python-fallback

gounthar commented Mar 18, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

gounthar Mar 19, 2026

Uh oh!

gounthar Mar 19, 2026

Uh oh!

gounthar Mar 19, 2026

Uh oh!

gounthar Mar 19, 2026

Uh oh!

gounthar commented Mar 19, 2026 •

edited

Loading

Uh oh!

gounthar commented Mar 19, 2026 •

edited

Loading

Uh oh!

weiji14 Mar 30, 2026 •

edited

Loading

Uh oh!

gounthar commented Mar 30, 2026 •

edited

Loading

Uh oh!

weiji14 commented Mar 30, 2026

Uh oh!

gounthar commented Mar 30, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

gounthar commented Mar 18, 2026

Summary

Changes

Behavior

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

gounthar Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

gounthar Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

gounthar Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

gounthar Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

gounthar commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gounthar commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

weiji14 Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gounthar commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

weiji14 commented Mar 30, 2026

Uh oh!

gounthar commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gounthar commented Mar 19, 2026 •

edited

Loading

gounthar commented Mar 19, 2026 •

edited

Loading

weiji14 Mar 30, 2026 •

edited

Loading

gounthar commented Mar 30, 2026 •

edited

Loading

gounthar commented Mar 30, 2026 •

edited

Loading