setup-python/README.md

setup-python

This action provides the following functionalities for GitHub Actions users:

• Optionally downloading and installing the requested version of Python/PyPy and adding it to the PATH
• Optionally caching dependencies for pip, pipenv and poetry
• Registering problem matchers for error output

Basic usage

See action.yml

Python

steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4 # <- v4 is a major release tag of the action: https://github.com/actions/setup-python/tags
  with:
    python-version: '3.10' 
- run: python my_script.py

PyPy

steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4 
  with:
    python-version: 'pypy3.9' 
- run: python my_script.py

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

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/PyPy on GitHub hosted runners, check out GitHub Actions Virtual Environments.

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.

Supported architectures

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

Caching packages dependencies

The action has built-in functionality for caching and restoring dependencies. It uses actions/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 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 want to be used.

• For pip, the action will cache global cache directory
• For pipenv, the action will cache virtualenv directory
• For poetry, the action will cache virtualenv directory

Caching pip dependencies:

steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
  with:
    python-version: '3.9'
    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 that can lead to an increase in total build time.

The requirements file format allows to specify dependency versions using logical operators (for example chardet>=3.0.4) or specify 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 data of the Advanced usage guide.

Advanced usage

• Using python-version input
• Using python-version-file input
• Check latest version
• Caching packages data
• Environment variables and action's outputs
• Available versions of Python and PyPy
• Hosted tool cache
• Using setup-python with a self hosted runner
• Using setup-python on GHES

License

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

Contributions

Contributions are welcome! See our Contributor's Guide.