actions/setup-python

Install a specific Python version and cache pip, pipenv, or poetry dependencies.

Official actionCategory: Language & Toolchain SetupLatest v5View on GitHub

What it does

actions/setup-python installs a chosen Python version and exposes it on PATH. It supports caching for pip, pipenv, and poetry via the cache input.

It pairs naturally with a build matrix to test several Python versions in parallel.

Usage

workflow (.yml)

jobs:
  test:
    strategy:
      matrix:
        python-version: ['3.10', '3.11', '3.12']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: 'pip'
      - run: pip install -r requirements.txt

Inputs

Input	Description	Default	Required
`python-version`	Version spec, e.g. 3.12 or 3.x.	-	No
`python-version-file`	Read the version from a file such as .python-version.	-	No
`cache`	Dependency cache: pip, pipenv, or poetry.	-	No
`cache-dependency-path`	Glob for the file(s) used in the cache key.	-	No
`allow-prereleases`	Allow prerelease versions to match.	`false`	No

Outputs

Output	Description
`python-version`	The version that was installed.
`cache-hit`	true if an exact dependency cache was restored.
`python-path`	Absolute path to the Python executable.

Notes

For cache: pip, a requirements file must exist to key the cache. Point cache-dependency-path at it if it is not at the repo root.

Common errors

Version 3.x.y is not available usually means a patch version that is not built for the runner architecture. Use a minor spec like 3.12.
A cache warning about a missing dependency file means cache is set but no requirements/lock file was found.

Security and pinning

Pin setup-python to a commit SHA rather than a mutable tag.

Frequently asked questions

How do I test multiple Python versions?

Use a strategy.matrix over python-version and pass the matrix value into setup-python.

References

GitHub Actions documentation