setup-python

25 March 2025 update: upstream actions/setup-python v5.5.0 now includes support for free-threaded CPython. Please use that instead of this fork.

This action provides the following functionality for GitHub Actions users:

Installing a version of Python or PyPy and (by default) adding it to the PATH
Optionally caching dependencies for pip, pipenv and poetry
Registering problem matchers for error output

Free-threaded Python Support

This is a fork of the "official" setup-python GitHub Action. We made this available to allow setting up CI with free-threaded Python while we wait for official upstream support. Hopefully, coming soon.

Caveats

Since setup-python relies on the Python.org installers, the limitations related to installing free-threaded Python on Windows are also present here.

In particular, if you install both a free-threaded and standard build of Python (e.g. both versions 3.13 and 3.13t) in the same Actions environment, only one of the specified versions will end up installed on the runner.

To work around this limitation, we suggest ensuring that any CI runs using the free-threaded build on Windows only activate one Python version.

Basic usage

See action.yml

Python

steps:
- uses: actions/checkout@v4
- uses: Quansight-Labs/setup-python@v5
  with:
    python-version: '3.13t'  # Use free-threaded version
- run: python my_script.py

PyPy

steps:
- uses: actions/checkout@v4
- uses: Quansight-Labs/setup-python@v5
  with:
    python-version: 'pypy3.10'
- run: python my_script.py

GraalPy

steps:
- uses: actions/checkout@v4
- uses: Quansight-Labs/setup-python@v5
  with:
    python-version: 'graalpy-24.0'
- run: python my_script.py

Free threaded Python

steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
  with:
    python-version: '3.13t'
- run: python my_script.py

The python-version input is optional. If not supplied, the action will try to resolve the version from the default .python-version file. If the .python-version file doesn't exist Python or PyPy version from the PATH will be used. The default version of Python or PyPy in PATH varies between runners and can be changed unexpectedly so we recommend always setting Python version explicitly using the python-version or python-version-file inputs.

The action will first check the local tool cache for a semver match. If unable to find a specific version in the tool cache, the action will attempt to download a version of Python from GitHub Releases and for PyPy from the official PyPy's dist.

For information regarding locally cached versions of Python or PyPy on GitHub hosted runners, check out GitHub Actions Runner Images.

Supported version syntax

The python-version input supports the Semantic Versioning Specification and some special version notations (e.g. semver ranges, x.y-dev syntax, etc.), for detailed examples please refer to the section: Using python-version input of the Advanced usage guide.

Additionally, this action supports free-threaded CPython distributions, using the x.yt syntax.

Supported architectures

Using the architecture input, it is possible to specify the required Python or PyPy interpreter architecture: x86, x64, or arm64. If the input is not specified, the architecture defaults to the host OS architecture.

Caching packages dependencies

The action has built-in functionality for caching and restoring dependencies. It uses toolkit/cache under the hood for caching dependencies but requires less configuration settings. Supported package managers are pip, pipenv and poetry. The cache input is optional, and caching is turned off by default.

The action defaults to searching for a dependency file (requirements.txt or pyproject.toml for pip, Pipfile.lock for pipenv or poetry.lock for poetry) in the repository, and uses its hash as a part of the cache key. Input cache-dependency-path is used for cases when multiple dependency files are used, they are located in different subdirectories or different files for the hash that want to be used.

For pip, the action will cache the global cache directory
For pipenv, the action will cache virtualenv directory
For poetry, the action will cache virtualenv directories -- one for each poetry project found

Caching pip dependencies:

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

Note: Restored cache will not be used if the requirements.txt file is not updated for a long time and a newer version of the dependency is available which can lead to an increase in total build time.

The requirements file format allows for specifying dependency versions using logical operators (for example chardet>=3.0.4) or specifying dependencies without any versions. In this case the pip install -r requirements.txt command will always try to install the latest available package version. To be sure that the cache will be used, please stick to a specific dependency version and update it manually if necessary.

See examples of using cache and cache-dependency-path for pipenv and poetry in the section: Caching packages of the Advanced usage guide.

Advanced usage

Using the python-version input
Using the python-version-file input
Check latest version
Caching packages
Outputs and environment variables
Available versions of Python, PyPy and GraalPy
Hosted tool cache
Using setup-python with a self-hosted runner
Using setup-python on GHES
Allow pre-releases

Recommended permissions

When using the setup-python action in your GitHub Actions workflow, it is recommended to set the following permissions to ensure proper functionality:

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

License

The scripts and documentation in this project are released under the MIT License.

Contributions

Contributions are welcome! See our Contributor's Guide.