You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+144Lines changed: 144 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -47,7 +47,151 @@ The `python-version` input supports the [Semantic Versioning Specification](http
47
47
48
48
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`.
49
49
50
+
<<<<<<< HEAD
50
51
## Caching packages dependencies
52
+
=======
53
+
Download and set up the latest stable version of Python (for specified major version):
54
+
```yaml
55
+
steps:
56
+
- uses: actions/checkout@v3
57
+
- uses: actions/setup-python@v4
58
+
with:
59
+
python-version: '3.x'
60
+
- run: python my_script.py
61
+
```
62
+
63
+
Download and set up PyPy:
64
+
65
+
```yaml
66
+
jobs:
67
+
build:
68
+
runs-on: ubuntu-latest
69
+
strategy:
70
+
matrix:
71
+
python-version:
72
+
- 'pypy3.7' # the latest available version of PyPy that supports Python 3.7
73
+
- 'pypy3.7-v7.3.3' # Python 3.7 and PyPy 7.3.3
74
+
- 'pypy3.8' # the latest available version of PyPy that supports Python 3.8
75
+
steps:
76
+
- uses: actions/checkout@v3
77
+
- uses: actions/setup-python@v4
78
+
with:
79
+
python-version: ${{ matrix.python-version }}
80
+
- run: python my_script.py
81
+
```
82
+
More details on PyPy syntax and examples of using preview / nightly versions of PyPy can be found in the [Available versions of PyPy](#available-versions-of-pypy) section.
83
+
84
+
An output is available with the absolute path of the python interpreter executable if you need it:
85
+
```yaml
86
+
jobs:
87
+
build:
88
+
runs-on: ubuntu-latest
89
+
steps:
90
+
- uses: actions/checkout@v3
91
+
- uses: actions/setup-python@v4
92
+
id: cp310
93
+
with:
94
+
python-version: "3.10"
95
+
- run: pipx run --python '${{ steps.cp310.outputs.python-path }}' nox --version
96
+
```
97
+
98
+
>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.
99
+
100
+
# Getting started with Python + Actions
101
+
102
+
Check out our detailed guide on using [Python with GitHub Actions](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-python-with-github-actions).
103
+
104
+
# Available versions of Python
105
+
106
+
`setup-python` is able to configure Python from two sources:
107
+
108
+
- Preinstalled versions of Python in the tools cache on GitHub-hosted runners.
109
+
- For detailed information regarding the available versions of Python that are installed, see [Supported software](https://docs.github.com/en/actions/reference/specifications-for-github-hosted-runners#supported-software).
110
+
- For every minor version of Python, expect only the latest patch to be preinstalled.
111
+
- 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.
112
+
- 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.
113
+
- 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*.
114
+
- Downloadable Python versions from GitHub Releases ([actions/python-versions](https://github.com/actions/python-versions/releases)).
115
+
- All available versions are listed in the [version-manifest.json](https://github.com/actions/python-versions/blob/main/versions-manifest.json) file.
116
+
- If there is a specific version of Python that is not available, you can open an issue here
117
+
118
+
**Note:** Python versions used in this action are generated in the [python-versions](https://github.com/actions/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](https://github.com/actions/python-versions) repository.
119
+
120
+
# Available versions of PyPy
121
+
122
+
`setup-python` is able to configure PyPy from two sources:
123
+
124
+
- Preinstalled versions of PyPy in the tools cache on GitHub-hosted runners
125
+
- For detailed information regarding the available versions of PyPy that are installed, see [Supported software](https://docs.github.com/en/actions/reference/specifications-for-github-hosted-runners#supported-software).
126
+
- For the latest PyPy release, all versions of Python are cached.
127
+
- 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`.
128
+
129
+
- Downloadable PyPy versions from the [official PyPy site](https://downloads.python.org/pypy/).
130
+
- All available versions that we can download are listed in [versions.json](https://downloads.python.org/pypy/versions.json) file.
131
+
- PyPy < 7.3.3 are not available to install on-flight.
132
+
- If some versions are not available, you can open an issue in https://foss.heptapod.net/pypy/pypy/
133
+
134
+
# Hosted Tool Cache
135
+
136
+
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.
GitHub virtual environments are setup in [actions/virtual-environments](https://github.com/actions/virtual-environments). During the setup, the available versions of Python and PyPy are automatically downloaded, setup and documented.
145
+
- Tools cache setup for Ubuntu: [Install-Toolset.ps1](https://github.com/actions/virtual-environments/blob/main/images/linux/scripts/installers/Install-Toolset.ps1) [Configure-Toolset.ps1](https://github.com/actions/virtual-environments/blob/main/images/linux/scripts/installers/Configure-Toolset.ps1)
146
+
- Tools cache setup for Windows: [Install-Toolset.ps1](https://github.com/actions/virtual-environments/blob/main/images/win/scripts/Installers/Install-Toolset.ps1) [Configure-Toolset.ps1](https://github.com/actions/virtual-environments/blob/main/images/win/scripts/Installers/Configure-Toolset.ps1)
147
+
148
+
# Specifying a Python version
149
+
150
+
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`)
151
+
- 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.
152
+
- MSI installers are used on Windows for this, so runs will take a little longer to set up vs Mac and Linux.
153
+
154
+
You should specify only a major and minor version if you are okay with the most recent patch version being used.
155
+
- There will be a single patch version already installed on each runner for every minor version of Python that is supported.
156
+
- 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.
157
+
- 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.
158
+
159
+
# Specifying a PyPy version
160
+
The version of PyPy should be specified in the format `pypy<python_version>[-v<pypy_version>]` or `pypy-<python_version>[-v<pypy_version>]`.
161
+
The `<pypy_version>` parameter is optional and can be skipped. The latest version will be used in this case.
162
+
163
+
```
164
+
pypy3.7 or pypy-3.7 # the latest available version of PyPy that supports Python 3.7
165
+
pypy3.8 or pypy-3.8 # the latest available version of PyPy that supports Python 3.8
166
+
pypy2.7 or pypy-2.7 # the latest available version of PyPy that supports Python 2.7
167
+
pypy3.7-v7.3.3 or pypy-3.7-v7.3.3 # Python 3.7 and PyPy 7.3.3
168
+
pypy3.7-v7.x or pypy-3.7-v7.x # Python 3.7 and the latest available PyPy 7.x
169
+
pypy3.7-v7.3.3rc1 or pypy-3.7-v7.3.3rc1 # Python 3.7 and preview version of PyPy
170
+
pypy3.7-nightly or pypy-3.7-nightly # Python 3.7 and nightly PyPy
171
+
```
172
+
173
+
Note: `pypy2` and `pypy3` have been removed in v3. Use the format above instead.
174
+
175
+
# Check latest version
176
+
177
+
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.
178
+
179
+
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.
180
+
181
+
> Setting `check-latest` to `true` has performance implications as downloading `Python/PyPy` versions is slower than using cached versions.
182
+
183
+
```yaml
184
+
steps:
185
+
- uses: actions/checkout@v3
186
+
- uses: actions/setup-python@v3
187
+
with:
188
+
python-version: '3.7'
189
+
check-latest: true
190
+
- run: python my_script.py
191
+
```
192
+
193
+
# Caching packages dependencies
194
+
>>>>>>> main
51
195
52
196
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.
0 commit comments