setup-python

Python

• Preinstalled: Available on GitHub-hosted runners. For minor versions, only the latest patch is typically preinstalled (e.g., 3.12 gets 3.12.x). Use -dev (e.g., 3.14-dev) for the latest patch including alpha/beta releases.
• Downloadable: Available via actions/python-versions from GitHub Releases.

PyPy

• Preinstalled: Available on GitHub-hosted runners. Note that cached versions may have a 1-2 week delay. To use a brand new release immediately, specify the exact version (e.g., pypy3.10-v7.3.17).
• Downloadable: Available from the official PyPy site. Versions < 7.3.3 cannot be installed on-flight.

GraalPy

• Downloadable: Available from the official GraalPy repository.

When using GitHub Enterprise Server (GHES), setup-python downloads distributions from actions/python-versions on github.com.

• Unauthenticated Requests: By default, these are limited to 60 requests per hour per IP. This can be problematic for GHES runners sharing an IP via NAT.
• Automatic Fallback: If the rate limit is reached, the action automatically leverages the raw API to retrieve the version-manifest, which does not impose a rate limit and allows for unrestricted consumption.

Python packages for macOS are non-relocatable due to fixed shared library paths and must be installed in /Users/runner/hostedtoolcache.

Before using setup-python on a macOS self-hosted runner, you must:

1. Create the directory /Users/runner/hostedtoolcache.
2. Grant the runner write access to that directory (e.g., via chown).

Example command to grant access: sudo chown runner-user:runner-group /Users/runner/hostedtoolcache.

The python-version input accepts a list of versions. When multiple versions are provided, the action installs all of them, and the last version in the list is set as the default version for the environment.

# Multiple Python versions
- uses: actions/setup-python@v7
  with:
    python-version: |
        3.11
        3.12
        3.13

# Multiple PyPy versions
- uses: actions/setup-python@v7
  with:
    python-version: |
        pypy-3.10-v7.3.x
        pypy3.10-nightly
        pypy3.9

Instead of hardcoding a version in your workflow, you can use the python-version-file input to point to a file containing the version specification.

Supported file types include:

• .python-version (asdf standard)
• pyproject.toml
• .tool-versions (asdf standard)
• Pipfile

Note: If both python-version and python-version-file are provided, python-version-file is ignored.

steps:
- uses: actions/checkout@v7
- uses: actions/setup-python@v7
  with:
    python-version-file: '.python-version'
- run: python my_script.py

You can use GitHub Actions matrix strategy to test your code against multiple Python or PyPy versions. You can also use the exclude keyword to skip specific combinations (e.g., skipping a specific Python version on a specific OS).

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ['3.9', '3.10', '3.11', 'pypy3.9']
        exclude:
          - os: macos-latest
            python-version: '3.9'
          - os: windows-latest
            python-version: '3.9'
    steps:
      - uses: actions/checkout@v7
      - name: Set up Python
        uses: actions/setup-python@v7
        with:
          python-version: ${{ matrix.python-version }}

To use setup-python on Ubuntu self-hosted runners:

• Tool Cache Location: By default, tools are installed to the directory defined by RUNNER_TOOL_CACHE. To change this, set the AGENT_TOOLSDIRECTORY environment variable.
  • Temporary (current shell): export AGENT_TOOLSDIRECTORY=/path/to/folder
  • Permanent (service): Add AGENT_TOOLSDIRECTORY=/path/to/folder to an .env file in the runner's directory.
• Permissions: The user starting the runner must have write access to the tool cache directory. You can grant access by ensuring the runner user owns the directory or is in the owning group. A quick way to grant access is using chown: sudo chown runner-user:runner-group /path/to/folder.

To use setup-python on Windows self-hosted runners, ensure the following requirements are met:

• Administrator Privileges: The runner must run with administrator privileges to install new Python versions.
• Service Permissions: If running as a service, the service account (e.g., NT AUTHORITY\NETWORK SERVICE) must have appropriate write permissions.
• 7zip: Must be installed and added to the PATH for extracting Python files.
• MSI Installers: The action uses MSI installers. Note that the 3.8 MSI installer prevents installing another 3.8 version; manually remove previous 3.8 versions via "Apps & Features" if installation fails.
• Tool Cache Location: By default, tools are installed to the directory defined by RUNNER_TOOL_CACHE. You can change this location by setting the AGENT_TOOLSDIRECTORY environment variable.

The action provides built-in caching for pip, pipenv, and poetry. Caching is disabled by default; you must set the cache input to enable it.

• pip: Caches the global cache directory. Looks for requirements.txt by default.
• pipenv: Caches the virtualenv directory. Looks for Pipfile.lock by default.
• poetry: Caches virtualenv directories (one for each project found). Looks for poetry.lock by default.

Use cache-dependency-path if your dependency files are in subdirectories or if you use multiple files and want to specify which one should be used for the cache key hash.

steps:
- uses: actions/checkout@v7
- uses: actions/setup-python@v7
  with:
    python-version: '3.13'
    cache: 'pip' # caching pip dependencies
- run: pip install -r requirements.txt

To ensure the action can properly check out code and install dependencies, it is recommended to set the following permissions in your workflow:

permissions:
  contents: read # access to check out code and install dependencies