Introduction

actions/setup-python fails early when the requested interpreter version is unavailable on the runner image or cannot be downloaded from the action's version manifest. This often happens after a repository pins an exact patch release, keeps an end-of-life Python version too long, or moves from GitHub-hosted to self-hosted runners without checking what versions are actually installable.

Symptoms

  • setup-python reports that the requested version could not be found
  • The workflow works locally with pyenv or asdf, but CI cannot install the same version
  • An exact patch release such as 3.8.10 fails while a broader 3.8 or current version would work
  • A self-hosted runner fails while GitHub-hosted runners succeed

Common Causes

  • The workflow pins an overly specific or unavailable patch version
  • The requested Python version is end-of-life or no longer present on the chosen runner image
  • .python-version or workflow YAML requests a different version than the project actually supports
  • A self-hosted runner cannot fetch or cache the requested interpreter

Step-by-Step Fix

  1. 1.Check the exact version requested by the workflow
  2. 2.Look at both the workflow file and any python-version-file source such as .python-version.
yaml
- uses: actions/setup-python@v5
  with:
    python-version: "3.12"
  1. 1.Prefer supported minor versions over fragile patch pins
  2. 2.Exact patch versions are more likely to disappear from runner images or become unavailable in automated install paths.
yaml
- uses: actions/setup-python@v5
  with:
    python-version-file: ".python-version"
  1. 1.Verify self-hosted runner support if the workflow is not GitHub-hosted
  2. 2.On self-hosted runners, the issue may be outbound network access, local package availability, or missing tooling rather than the workflow syntax itself.
bash
python3 --version
which python3
  1. 1.Retest with one known-good supported version before restoring matrices
  2. 2.If a matrix job is failing, prove a single supported version works first, then widen back out.

Prevention

  • Keep Python version declarations aligned across workflow files and local development tooling
  • Prefer supported minor releases such as 3.11 or 3.12 over exact patch pins
  • Plan Python upgrades before the current runtime reaches end-of-life
  • Validate self-hosted runner language toolchains after image or network changes