setup-python/README.md

95 lines
5.5 KiB
Markdown
Raw Normal View History

# setup-python
2019-08-20 10:27:52 -04:00
<p align="left">
<a href="https://github.com/actions/setup-python"><img alt="GitHub Actions status" src="https://github.com/actions/setup-python/workflows/Main%20workflow/badge.svg"></a>
</p>
2022-07-13 07:34:22 -04:00
This action provides the following functionalities for GitHub Actions users:
2019-08-20 10:27:52 -04:00
- 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
2019-08-20 10:27:52 -04:00
## Basic usage
2019-08-20 10:27:52 -04:00
See [action.yml](action.yml)
2022-07-13 05:15:35 -04:00
**Python**
2019-08-20 10:27:52 -04:00
```yaml
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
```
2022-07-13 05:15:35 -04:00
**PyPy**
```yaml
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with:
2022-07-13 06:17:04 -04:00
python-version: 'pypy3.9'
2022-07-13 05:15:35 -04:00
- 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`.
2022-07-12 11:32:40 -04:00
The action will first check the local [tool cache](docs/advanced-usage.md#hosted-tool-cache) for a [semver](https://github.com/npm/node-semver#versions) 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](https://github.com/actions/python-versions/releases) and for PyPy from the official [PyPy's dist](https://downloads.python.org/pypy/).
For information regarding locally cached versions of Python/PyPy on GitHub hosted runners, check out [GitHub Actions Virtual Environments](https://github.com/actions/virtual-environments).
## Supported version syntax
2019-12-23 11:51:09 -05:00
2022-07-13 06:17:04 -04:00
The `python-version` input supports the [Semantic Versioning Specification](https://semver.org/) 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](docs/advanced-usage.md#using-python-version-input) of the [Advanced usage](docs/advanced-usage.md) guide.
2019-12-23 11:51:09 -05:00
## Supported architectures
2019-12-23 11:51:09 -05:00
2022-07-13 07:34:22 -04:00
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`.
2019-12-23 11:51:09 -05:00
## Caching packages dependencies
The action has built-in functionality for caching and restoring dependencies. It uses [actions/cache](https://github.com/actions/toolkit/tree/main/packages/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:**
```yaml
steps:
- uses: actions/checkout@v3
2022-06-09 03:54:52 -04:00
- 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.
2019-12-23 11:51:09 -05:00
See examples of using `cache` and `cache-dependency-path` for `pipenv` and `poetry` in the section: [Caching packages data](docs/advanced-usage.md#caching-packages-data) of the [Advanced usage](docs/advanced-usage.md) guide.
## Advanced usage
- [Using python-version input](docs/advanced-usage.md#using-python-version-input)
- [Using python-version-file input](docs/advanced-usage.md#using-python-version-file-input)
- [Check latest version](docs/advanced-usage.md#check-latest-version)
- [Caching packages data](docs/advanced-usage.md#caching-packages-data)
- [Environment variables and action's outputs](docs/advanced-usage.md#environment-variables-and-actions-outputs)
- [Available versions of Python and PyPy](docs/advanced-usage.md#available-versions-of-python-and-pypy)
2022-07-12 11:32:40 -04:00
- [Hosted tool cache](docs/advanced-usage.md#hosted-tool-cache)
- [Using `setup-python` with a self hosted runner](docs/advanced-usage.md#using-setup-python-with-a-self-hosted-runner)
- [Using `setup-python` on GHES](docs/advanced-usage.md#using-setup-python-on-ghes)
## License
2019-08-20 10:27:52 -04:00
2020-10-14 05:59:10 -04:00
The scripts and documentation in this project are released under the [MIT License](LICENSE).
2019-08-20 10:27:52 -04:00
## Contributions
2019-08-20 10:27:52 -04:00
Contributions are welcome! See our [Contributor's Guide](docs/contributors.md).