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

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>

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.

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

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

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

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>

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>

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

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?

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.

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?

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#25). Once those installations work properly, the fallback should look there for the requested version instead of only checking system Python.

For anyone watching, it’s on my immediate todo list to unblock that, feel free to have a look in the meantime and submit a PR to https://github.com/riseproject-dev/riscv-runner-images. Relevant file is at runner/Dockerfile.ubuntu

Cross-posting here: #1288 (comment)

We can also add an input similar to actions/setup-go#721 so that users can conditionally specify another url to download the Python binary from.

Good point, @luhenry. The two approaches are complementary:

The system Python fallback in this PR is zero-config: no input needed, works as soon as there's a compatible python3 in PATH. Useful for projects that just need 3.x to match whatever the runner image ships.
A python-download-base-url input (like go-download-base-url in setup-go#721) would let users point to a custom distribution; for instance, BayLibre's RISE Python builds, or any community-maintained riscv64 binaries, and request a specific version like 3.13.

The limitation of the current PR is exactly what @weiji14 ran into: python-version: "3.13" fails if the system only has 3.12. A custom URL input would solve that case properly.

Would you be willing to add that input, or should I extend this PR to include it alongside the system fallback?

For reference: @luhenry is now building riscv64 Python binaries at https://github.com/riseproject-dev/python-versions, following the same manifest format as actions/python-versions (~140 builds currently running). Once python-download-base-url lands, the usage for riscv64 runners would be something like:

- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
    python-download-base-url: 'https://raw.githubusercontent.com/riseproject-dev/python-versions/main'

That covers the specific-version case (3.12, 3.13, etc.) that the current system-fallback PR cannot handle. The two approaches remain complementary: system fallback for zero-config use, custom URL for pinned versions.

I’ll submit a separate PR to add python-download-base-url

Details

uses: actions/setup-python@v5
with:
python-version: '3.12'
python-download-base-url: 'https://raw.githubusercontent.com/riseproject-dev/python-versions/main'

Relates to #1302

Thanks for #1302 -- the mirror / mirror-token approach looks more solid than what I had sketched with python-download-base-url. The two PRs might still cover different cases: #1302 handles pinned versions from a custom mirror, while this one is a zero-config fallback for when the manifest has no entries for the architecture at all -- though I'm not sure if that distinction is worth the added complexity. Happy to close this one if you feel the mirror input covers enough ground.

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

luhenry mentioned this pull request Apr 6, 2026

feat: Add mirror and mirror-token inputs for custom Python distribution sources #1302

Open

2 tasks

weiji14 mentioned this pull request Apr 6, 2026

👷 Build wheels for riscv64 weiji14/cog3pio#88

Merged

coderabbitai Bot mentioned this pull request Apr 26, 2026

ci: discover opt Python path dynamically + sync upstream gounthar/tiktoken#8

Merged

2 tasks

rgommers mentioned this pull request May 12, 2026

ENH: add riscv64 to the wheel build matrix numpy/numpy#30995

Closed

gounthar mentioned this pull request May 15, 2026

Add riscv64 architecture support #1288

Open

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

+                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}.`
+                        );
+                      }

+                      '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}.`

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

+                          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}.`);

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

Uh oh!

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

feat: fall back to system Python when pre-built binaries unavailable#1289gounthar wants to merge 3 commits intoactions:mainactions/setup-python:mainfrom gounthar:feat/system-python-fallbackgounthar/setup-python:feat/system-python-fallbackCopy head branch name to clipboard

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!

luhenry commented Apr 1, 2026

Uh oh!

luhenry commented Apr 5, 2026

Uh oh!

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

Uh oh!

Uh oh!

gounthar commented Apr 5, 2026

Uh oh!

luhenry commented Apr 5, 2026

Uh oh!

lawalmikky46-prog commented Apr 5, 2026

Uh oh!

luhenry commented Apr 6, 2026

Uh oh!

gounthar commented Apr 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

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

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

gounthar commented Apr 5, 2026 •
edited
Loading