setup-python
这个 Action 为 GitHub Actions 用户提供以下功能:
- 安装 Python 或 PyPy 的特定版本,并(默认情况下)将其添加到 PATH
- 可选择缓存 pip、pipenv 和 poetry 的依赖项
- 为错误输出注册问题匹配器
基本用法
参见 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
python-version
输入是可选的。如果未提供,该 Action 将尝试从默认的 .python-version
文件解析版本。如果 .python-version
文件不存在,将使用 PATH 中的 Python 或 PyPy 版本。PATH 中的 Python 或 PyPy 默认版本在不同运行器之间可能有所不同,并且可能会意外更改,因此我们建议始终使用 python-version
或 python-version-file
输入显式设置 Python 版本。
该 Action 首先会在本地工具缓存中查找 semver 匹配项。如果在工具缓存中找不到特定版本,该 Action 将尝试从 GitHub Releases 下载 Python 版本,或从官方 PyPy 发布页面 下载 PyPy 版本。
有关 GitHub 托管运行器上本地缓存的 Python 或 PyPy 版本的信息,请查看 GitHub Actions Runner Images。
支持的版本语法
python-version
输入支持语义化版本规范和一些特殊版本表示法(例如 semver 范围
、x.y-dev 语法
等),详细示例请参阅 高级用法 指南中的 使用 python-version 输入 部分。
支持的架构
使用 architecture
输入可以指定所需的 Python 或 PyPy 解释器架构:x86
或 x64
。如果未指定输入,架构默认为 x64
。
缓存包依赖
该 Action 内置了缓存和恢复依赖项的功能。它在底层使用 toolkit/cache 进行依赖项缓存,但需要的配置设置更少。支持的包管理器有 pip
、pipenv
和 poetry
。cache
输入是可选的,默认情况下缓存是关闭的。
该 Action 默认在仓库中搜索依赖文件(pip 的 requirements.txt
或 pyproject.toml
,pipenv 的 Pipfile.lock
,或 poetry 的 poetry.lock
),并使用其哈希值作为缓存键的一部分。cache-dependency-path
输入用于使用多个依赖文件、它们位于不同子目录或想要使用不同文件进行哈希的情况。
- 对于
pip
,该 Action 将缓存全局缓存目录 - 对于
pipenv
,该 Action 将缓存虚拟环境目录 - 对于
poetry
,该 Action 将缓存虚拟环境目录 -- 每个找到的 poetry 项目一个
缓存 pip 依赖:
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.9'
cache: 'pip' # 缓存 pip 依赖
- run: pip install -r requirements.txt
注意: 如果长时间未更新 requirements.txt 文件,而有更新的依赖版本可用,恢复的缓存将不会被使用,这可能会导致总构建时间增加。
requirements 文件格式允许使用逻辑运算符(例如 chardet>=3.0.4)指定依赖版本或不指定任何版本。在这种情况下,pip install -r requirements.txt 命令将始终尝试安装最新可用的包版本。为确保使用缓存,请坚持使用特定的依赖版本,并在必要时手动更新。
有关在 pipenv
和 poetry
中使用 cache
和 cache-dependency-path
的示例,请参阅 高级用法 指南中的 缓存包 部分。
高级用法
- 使用 python-version 输入
- 使用 python-version-file 输入
- 检查最新版本
- 缓存包
- 输出和环境变量
- Python、PyPy 和 GraalPy 的可用版本
- 托管工具缓存
- 在自托管运行器上使用 setup-python
- 在 GHES 上使用 setup-python
- 允许预发布版本
许可证
本项目中的脚本和文档在 MIT 许可证 下发布。
贡献
欢迎贡献!请参阅我们的贡献者指南。