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).

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>

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gounthar commented Mar 19, 2026 •

edited

Loading

gounthar commented Mar 19, 2026 •

edited

Loading