GitHub Actions setup-python "Version not found" from a version file

setup-python can read the version from a file via python-version-file. If that file is missing, empty, or holds an unavailable version, the action cannot resolve a Python to install.

What this error means

The setup-python step fails to find a version when configured with python-version-file, because the referenced file is absent or specifies a version not available on the runner.

Error: The version '3.13.99' with arch 'x64' was not found for Ubuntu

Common causes

Version file missing or empty

The python-version-file path does not exist after checkout, or contains no usable version.

Version not available for the runner

The file pins a Python version that the runner image does not provide.

How to fix it

Point at a valid version file or pin directly

1. Commit a .python-version (or use pyproject.toml) with an available version.
2. Or set python-version directly to a supported value.
3. Run checkout before setup-python so the file exists.

- uses: actions/setup-python@v5
  with:
    python-version-file: '.python-version'

How to prevent it

• Commit a valid version file and keep it current.
• Pin versions that the runner image actually offers.
• Checkout before setup-python so the version file is present.

Related guides