setup-python
setup-python copied to clipboard
Set up your GitHub Actions workflow with a specific version of Python
setup-python
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
Basic usage
See action.yml
Python
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.10'
- run: python my_script.py
PyPy
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: 'pypy3.9'
- run: python my_script.py
GraalPy
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: 'graalpy-22.3'
- 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.
Supported architectures
Using architecture
input it is possible to specify the required Python or PyPy interpreter architecture: x86
or x64
. If the 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 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.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 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
License
The scripts and documentation in this project are released under the MIT License.
Contributions
Contributions are welcome! See our Contributor's Guide.