GitHub Actionsでpipの依存関係をキャッシュする
最終更新
GitHub Actionsでpipをキャッシュするには、actions/setup-pythonでcache: pipを設定します。pipのグローバルダウンロードキャッシュを、要件ファイルをキーとしてキャッシュします。uvへの切り替えが可能であれば、astral-sh/setup-uvが独自のストアをキャッシュし、インストールがはるかに高速になります。両方の手順を以下に示します。
オプション1: setup-pythonの組み込みキャッシュ
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v7
with:
python-version: "3.13"
cache: pip
- run: pip install -r requirements.txt
- run: pytest
setup-pythonのREADME(2026年10月確認)によると、cache: pipはグローバルなpipキャッシュディレクトリをキャッシュします。デフォルトでは、キーはリポジトリのルートにあるrequirements.txtまたはpyproject.tomlのハッシュで決まります。requirementsファイルが複数ある場合は、ファイル名を指定してください。
- uses: actions/setup-python@v7
with:
python-version: "3.13"
cache: pip
cache-dependency-path: |
requirements.txt
requirements-dev.txt
キャッシュはcacheを設定しない限り無効です。キーにはPythonのバージョンとOSも含まれるため、マトリックスでは各セルごとに1つのエントリが作成されます。
方法2: 明示的なactions/cache
- uses: actions/setup-python@v7
with:
python-version: "3.13"
- name: Get pip cache dir
id: pip-cache
run: echo "dir=$(pip cache dir)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v6
with:
path: ${{ steps.pip-cache.outputs.dir }}
key: pip-${{ runner.os }}-py3.13-${{ hashFiles('requirements*.txt') }}
restore-keys: |
pip-${{ runner.os }}-py3.13-
- run: pip install -r requirements.txt
pip cache dirは各OSに応じた正しいパスを返します(Linuxでは~/.cache/pip)。コンパイル済みのwheelはインタープリターごとにタグ付けされるため、キーにはPythonのバージョンを含める必要があります。
pipが実際にキャッシュするもの
pipはダウンロードしたwheelと、パッケージをソースからビルドした場合はそのビルド結果のwheelを保存します。古いC拡張のようなソースのみのパッケージでキャッシュがヒットすると、ダウンロードだけでなくコンパイルも省略できるため、効果はさらに大きくなります。
| キャッシュ | 効果がある対象 | 理由 |
|---|---|---|
| pip cache dir | あり | ダウンロードとローカルでのwheelビルドを省略できる |
仮想環境(.venv) | まれ | 1つのPythonビルドとパスに結び付くため、マイナーバージョンのアップグレードで壊れる |
~/.cache/pre-commit | はい(別途) | フック環境。キーは.pre-commit-config.yaml |
.pytest_cache, .mypy_cache, .ruff_cache | 場合による | 依存関係ではなくツールのキャッシュ |
仮想環境全体をキャッシュすると、インストールするものがないため速く見えることがあります。ただし、これは壊れやすい方法です。仮想環境には絶対パスとインタープリターへのリンクが含まれるため、ランナーイメージ上のPythonのパッチリリースによって環境が壊れる可能性があります。その速度が必要な場合は、ロックファイルとPythonバージョンの両方をキーにしたインプロジェクト仮想環境のPoetryを使うか、uvを使用してください。
オプション3: uv
uvはAstralによるインストーラーで、pipの代替として使えて高速です。そのセットアップアクションがキャッシュを自動で管理します。
- uses: actions/checkout@v6
- uses: astral-sh/setup-uv@v10
with:
enable-cache: true
cache-dependency-glob: |
**/pyproject.toml
**/uv.lock
- run: uv sync --frozen
- run: uv run pytest
setup-uvのREADME(2026年10月確認)によると、enable-cacheの既定値はautoで、GitHubホステッドランナーではキャッシュが有効に、セルフホステッドランナーでは無効になります。compiler.devを含むセルフホステッドランナーでは、enable-cache: trueを明示的に設定してください。setup-uvはプロジェクトをインストールしません。引き続きuv syncを実行する必要があります。pipスタイルのワークフローでは、uv pip install -r requirements.txtが同じキャッシュを使います。
キャッシュヒットの確認方法
- setup-pythonステップは
Cache restored from key: setup-python-Linux-...-pip-...と出力します。キャッシュがない場合はCache not foundと出力されます。 pip installの出力では、キャッシュから復元されたパッケージにDownloading ...ではなくUsing cached ...と表示されます。- キャッシュがないジョブの終了時には、後処理ステップで
Cache saved with key: ...と出力されます。 gh cache list --key pip- --limit 20(または--key setup-python)を実行すると、エントリのサイズと最終使用日時が一覧表示されます。
よくある間違い
- ロックファイルがない場合。バージョンを固定していない
requirements.txtだけでは、解決されるバージョンが変わってもキーは同じままです。pip-compile、uv pip compile、またはロックファイルでバージョンを固定してください。 - 存在しないファイルをハッシュしようとする場合。
cache: pipを指定し、requirements.txtやpyproject.tomlが存在しないと、setup-pythonはエラーになります。cache-dependency-pathを設定してください。 - Pythonバージョン間で1つのキーを共有する場合。明示的なキーにはバージョンを含めてください。setup-pythonでは既に含まれています。
site-packagesを直接キャッシュする場合。仮想環境をキャッシュする場合と同じく壊れやすくなります。- PRでのみ保存する場合。スコープのルールにより、PRのキャッシュは他のPRからは見えません。GitHub Actionsのキャッシュを参照してください。
テストスイートの実行が遅いのは、インストールの遅さとは別の問題です。pytestの遅いテストとGitHub ActionsでのDjangoの高速化を参照してください。
サイズと上限
pipのキャッシュは通常100 MBから1 GBです。データサイエンス系のスタック(torchやCUDAのwheel)は1つで数GBになることもあり、10 GBのリポジトリ上限をすぐに圧迫します。詳細はキャッシュの上限を参照してください。単一のwheelが非常に大きい場合は、ダウンロードが本当にボトルネックかどうかを確認してください。
よくある質問
site-packagesと仮想環境のどちらをキャッシュすべきですか?
基本的にはどちらも推奨しません。pipのダウンロードディレクトリをキャッシュするか、uvを使用してください。仮想環境のキャッシュは、キーに正確なPythonバージョンとロックファイルのハッシュを含めた場合にのみ安全です。
複数のrequirementsファイルがある場合、pipをどのようにキャッシュしますか?
1行ずつ、すべてcache-dependency-pathに渡してください。
CIだけのためにuvを導入しても安全ですか?
uvは標準のrequirements.txtとpyproject.tomlを読み取ります。まずはuv pip install -r requirements.txtを試してください。変更は1行だけです。
新しいブランチでpipのキャッシュがヒットしないのはなぜですか?
新しいブランチは、自身のキャッシュとデフォルトブランチのキャッシュを読み取れます。mainでキャッシュが一度も保存されていない場合、復元するものがありません。
次のステップ
Poetryを使っていますか?GitHub ActionsでPoetryをキャッシュする方法をご覧ください。全体像については、GitHub Actionsを高速化する方法を参照してください。compiler.devでは、同じジョブを8 vCPUのマシンで1分あたり$0.008で実行できます。詳しくは料金のページをご覧ください。
関連記事
- GitHub Actions で Cargo と Rust のビルドをキャッシュするSwatinem/rust-cache または actions/cache を使用して、GitHub Actions で Cargo レジストリ、git 依存関係、target ディレクトリをキャッシュします。キャッシュが肥大化しないように注意します。
- GitHub Actions で Go モジュールとビルドキャッシュをキャッシュするsetup-go または actions/cache を使用して、GitHub Actions で Go モジュール(GOMODCACHE)とビルドキャッシュ(GOCACHE)をキャッシュします。キー、go.sum、キャッシュヒットの確認方法を解説します。
- GitHub Actions で Gradle ビルドをキャッシュするgradle/actions/setup-gradle または actions/cache を使用して、GitHub Actions で Gradle の依存関係とビルドキャッシュをキャッシュします。キー、プルリクエストでの読み取り専用設定、クリーンアップ、確認方法を解説します。
- GitHub Actions で npm の依存関係をキャッシュするsetup-node または actions/cache を使用して、GitHub Actions で npm の依存関係をキャッシュします。動作する YAML、適切なキー、node_modules をキャッシュしない理由、キャッシュヒットの確認方法を解説します。