コンテンツへスキップ

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が同じキャッシュを使います。

キャッシュヒットの確認方法

  1. setup-pythonステップはCache restored from key: setup-python-Linux-...-pip-...と出力します。キャッシュがない場合はCache not foundと出力されます。
  2. pip installの出力では、キャッシュから復元されたパッケージにDownloading ...ではなくUsing cached ...と表示されます。
  3. キャッシュがないジョブの終了時には、後処理ステップでCache saved with key: ...と出力されます。
  4. gh cache list --key pip- --limit 20(または--key setup-python)を実行すると、エントリのサイズと最終使用日時が一覧表示されます。

よくある間違い

  1. ロックファイルがない場合。バージョンを固定していないrequirements.txtだけでは、解決されるバージョンが変わってもキーは同じままです。pip-compile、uv pip compile、またはロックファイルでバージョンを固定してください。
  2. 存在しないファイルをハッシュしようとする場合。cache: pipを指定し、requirements.txtやpyproject.tomlが存在しないと、setup-pythonはエラーになります。cache-dependency-pathを設定してください。
  3. Pythonバージョン間で1つのキーを共有する場合。明示的なキーにはバージョンを含めてください。setup-pythonでは既に含まれています。
  4. site-packagesを直接キャッシュする場合。仮想環境をキャッシュする場合と同じく壊れやすくなります。
  5. 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で実行できます。詳しくは料金のページをご覧ください。

compiler.devでこのpytestスイートを実行 カード登録不要 · 200 無料分

無料で試す