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.

<<<<<<< HEAD

Caching packages dependencies

======= Download and set up the latest stable version of Python (for specified major version):

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

Download and set up PyPy:

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version:
        - 'pypy3.7' # the latest available version of PyPy that supports Python 3.7
        - 'pypy3.7-v7.3.3' # Python 3.7 and PyPy 7.3.3
        - 'pypy3.8' # the latest available version of PyPy that supports Python 3.8
    steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python-version }}
    - run: python my_script.py

More details on PyPy syntax and examples of using preview / nightly versions of PyPy can be found in the Available versions of PyPy section.

An output is available with the absolute path of the python interpreter executable if you need it:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-python@v4
      id: cp310
      with:
        python-version: "3.10"
    - run: pipx run --python '${{ steps.cp310.outputs.python-path }}' nox --version

The environment variable pythonLocation also becomes available after Python or PyPy installation. It contains the absolute path to the folder where the desired version of Python or PyPy is installed.

Getting started with Python + Actions

Check out our detailed guide on using Python with GitHub Actions.

Available versions of Python

setup-python is able to configure Python from two sources:

• Preinstalled versions of Python in the tools cache on GitHub-hosted runners.
  • For detailed information regarding the available versions of Python that are installed, see Supported software.
  • For every minor version of Python, expect only the latest patch to be preinstalled.
  • If 3.8.1 is installed for example, and 3.8.2 is released, expect 3.8.1 to be removed and replaced by 3.8.2 in the tools cache.
  • If the exact patch version doesn't matter to you, specifying just the major and minor version will get you the latest preinstalled patch version. In the previous example, the version spec 3.8 will use the 3.8.2 Python version found in the cache.
  • Use -dev instead of a patch number (e.g., 3.11-dev) to install the latest patch version release for a given minor version, alpha and beta releases included.
• Downloadable Python versions from GitHub Releases (actions/python-versions).
  • All available versions are listed in the version-manifest.json file.
  • If there is a specific version of Python that is not available, you can open an issue here

Note: Python versions used in this action are generated in the python-versions repository. For macOS and Ubuntu images python versions are built from the source code. For Windows the python-versions repository uses installation executable. For more information please refer to the python-versions repository.

Available versions of PyPy

setup-python is able to configure PyPy from two sources:

• Preinstalled versions of PyPy in the tools cache on GitHub-hosted runners

  • For detailed information regarding the available versions of PyPy that are installed, see Supported software.
  • For the latest PyPy release, all versions of Python are cached.
  • Cache is updated with a 1-2 week delay. If you specify the PyPy version as pypy3.7 or pypy-3.7, the cached version will be used although a newer version is available. If you need to start using the recently released version right after release, you should specify the exact PyPy version using pypy3.7-v7.3.3 or pypy-3.7-v7.3.3.

• Downloadable PyPy versions from the official PyPy site.

  • All available versions that we can download are listed in versions.json file.
  • PyPy < 7.3.3 are not available to install on-flight.
  • If some versions are not available, you can open an issue in https://foss.heptapod.net/pypy/pypy/

Hosted Tool Cache

GitHub hosted runners have a tools cache that comes with a few versions of Python + PyPy already installed. This tools cache helps speed up runs and tool setup by not requiring any new downloads. There is an environment variable called RUNNER_TOOL_CACHE on each runner that describes the location of this tools cache and there is where you will find Python and PyPy installed. setup-python works by taking a specific version of Python or PyPy in this tools cache and adding it to PATH.

	Location
Tool Cache Directory	RUNNER_TOOL_CACHE
Python Tool Cache	RUNNER_TOOL_CACHE/Python/*
PyPy Tool Cache	RUNNER_TOOL_CACHE/PyPy/*

GitHub virtual environments are setup in actions/virtual-environments. During the setup, the available versions of Python and PyPy are automatically downloaded, setup and documented.

• Tools cache setup for Ubuntu: Install-Toolset.ps1 Configure-Toolset.ps1
• Tools cache setup for Windows: Install-Toolset.ps1 Configure-Toolset.ps1

Specifying a Python version

If there is a specific version of Python that you need and you don't want to worry about any potential breaking changes due to patch updates (going from 3.7.5 to 3.7.6 for example), you should specify the exact major, minor, and patch version (such as 3.7.5)

• The only downside to this is that set up will take a little longer since the exact version will have to be downloaded if the exact version is not already installed on the runner due to more recent versions.
• MSI installers are used on Windows for this, so runs will take a little longer to set up vs Mac and Linux.

You should specify only a major and minor version if you are okay with the most recent patch version being used.

• There will be a single patch version already installed on each runner for every minor version of Python that is supported.
• The patch version that will be preinstalled, will generally be the latest and every time there is a new patch released, the older version that is preinstalled will be replaced.
• Using the most recent patch version will result in a very quick setup since no downloads will be required since a locally installed version Python on the runner will be used.

Specifying a PyPy version

The version of PyPy should be specified in the format pypy<python_version>[-v<pypy_version>] or pypy-<python_version>[-v<pypy_version>]. The <pypy_version> parameter is optional and can be skipped. The latest version will be used in this case.

pypy3.7 or pypy-3.7 # the latest available version of PyPy that supports Python 3.7
pypy3.8 or pypy-3.8 # the latest available version of PyPy that supports Python 3.8
pypy2.7 or pypy-2.7 # the latest available version of PyPy that supports Python 2.7
pypy3.7-v7.3.3 or pypy-3.7-v7.3.3 # Python 3.7 and PyPy 7.3.3
pypy3.7-v7.x or pypy-3.7-v7.x # Python 3.7 and the latest available PyPy 7.x
pypy3.7-v7.3.3rc1 or pypy-3.7-v7.3.3rc1 # Python 3.7 and preview version of PyPy
pypy3.7-nightly or pypy-3.7-nightly # Python 3.7 and nightly PyPy

Note: pypy2 and pypy3 have been removed in v3. Use the format above instead.

Check latest version

The check-latest flag defaults to false. Use the default or set check-latest to false if you prefer stability and if you want to ensure a specific Python/PyPy version is always used.

If check-latest is set to true, the action first checks if the cached version is the latest one. If the locally cached version is not the most up-to-date, a Python/PyPy version will then be downloaded. Set check-latest to true if you want the most up-to-date Python/PyPy version to always be used.

Setting check-latest to true has performance implications as downloading Python/PyPy versions is slower than using cached versions.

steps:
  - uses: actions/checkout@v3
  - uses: actions/setup-python@v3
    with:
      python-version: '3.7'
      check-latest: true
  - run: python my_script.py

Caching packages dependencies

main

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.