コンテンツへスキップ

GitHub ActionsでPoetryの依存関係をキャッシュする

最終更新

GitHub ActionsでPoetryをキャッシュするには、actions/setup-pythonより前にPoetryをインストールし、cache: poetryを設定します。すると、setup-pythonがPoetryの仮想環境をキャッシュし、キーはpoetry.lockに基づいて作成されます。多くの人が間違えやすいのはステップの順序です。キャッシュステップでエラーが出た場合は、まずここを確認してください。

方法1: cache: poetryを使ったsetup-python

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Install Poetry
        run: pipx install poetry
      - uses: actions/setup-python@v7
        with:
          python-version: "3.13"
          cache: poetry
      - run: poetry install --no-interaction
      - run: poetry run pytest

setup-pythonのREADME(2026年10月時点で確認)によると、cache: poetryは仮想環境のディレクトリをキャッシュします。対象は見つかったPoetryプロジェクトごとで、デフォルトのキーはpoetry.lockのハッシュです。このアクションはPoetryを実行して対象ディレクトリを見つけるため、先にPoetryをインストールしておく必要があります。GitHub-hostedのUbuntuイメージにはpipxが事前にインストールされています。その他のランナーでは、先にpipxをインストールするか、pip install poetryを使用してください。

ロックファイルがサブディレクトリにある場合は、cache-dependency-pathを指定します。

- uses: actions/setup-python@v7
  with:
    python-version: "3.13"
    cache: poetry
    cache-dependency-path: services/api/poetry.lock

方法2: プロジェクト内仮想環境を使った明示的なactions/cache

Poetryは、デフォルトでは仮想環境を共有ディレクトリに、ハッシュ化された名前で作成します(Linuxでは~/.cache/pypoetry/virtualenvs)。仮想環境を.venvとしてプロジェクト内に作成すると、キャッシュ対象の固定パスが得られます。

- uses: actions/checkout@v6
- run: pipx install poetry
- uses: actions/setup-python@v7
  id: py
  with:
    python-version: "3.13"
- run: poetry config virtualenvs.in-project true
- uses: actions/cache@v6
  with:
    path: .venv
    key: venv-${{ runner.os }}-py${{ steps.py.outputs.python-version }}-${{ hashFiles('poetry.lock') }}
    restore-keys: |
      venv-${{ runner.os }}-py${{ steps.py.outputs.python-version }}-
- run: poetry install --no-interaction

この方法では次の3点が重要です。

  • キーには正確なPythonバージョンを含めます。steps.py.outputs.python-versionは、3.13.1のような完全なバージョンを返します。仮想環境にはそれを作成したインタープリターへのリンクが含まれます。ランナーイメージがPythonを更新すると、古いキーで復元された仮想環境は壊れます。キーに正確なバージョンを含めると、再構築が強制されます。
  • poetry installは引き続き実行します。キャッシュヒット時は、すでにすべてがインストールされているため数秒で完了します。restore-keysによる部分的な復元の場合は、変更された部分だけを追加または更新します。
  • キャッシュステップの前にvirtualenvs.in-projectを設定します。設定しないと、Poetryは別の場所に仮想環境を作成し、.venvは空のままになります。

方法3: ダウンロードキャッシュのみをキャッシュする

仮想環境をキャッシュしたくない場合は、Poetryのダウンロードキャッシュだけをキャッシュし、poetry installで毎回仮想環境を再構築させることもできます。

- uses: actions/cache@v6
  with:
    path: ~/.cache/pypoetry
    key: poetry-${{ runner.os }}-${{ hashFiles('poetry.lock') }}
    restore-keys: |
      poetry-${{ runner.os }}-

この方法は安全ですが、実行のたびにwheelの展開が行われるため低速です。実際のパスはランナー上でpoetry config cache-dirを使って確認してください。

キャッシュすべきものとすべきでないもの

項目キャッシュするか備考
プロジェクト内の.venv可能。キーにPythonバージョンを含める復元が最も速い
~/.cache/pypoetryあり安全。ダウンロードのみ節約
Poetry自体のインストール任意pipx install poetryは数秒で完了
dist/のビルド成果物なしリリースごとに再ビルド

仮想環境をキャッシュする場合は、Poetryのバージョンを固定してください(pipx install poetry==2.x)。Poetryをアップグレードすると環境の構成が変わることがあり、バージョンを固定しないとキーの情報が不完全になります。

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

  1. setup-pythonまたはcacheステップの出力でCache restored from key: ...を確認します。キャッシュが見つからない場合はCache not found for input keys: ...と表示されます。
  2. poetry installの出力で、ウォーム実行時はNo dependencies to install or updateと表示されます。コールド実行時は、各パッケージがInstalling ...として一覧表示されます。
  3. 明示的なactions/cacheを使う場合は、デバッグ中に出力を条件分岐に使えます。if: steps.cache.outputs.cache-hit != 'true'は、キャッシュがヒットしなかった場合のみ実行されます。
  4. gh cache list --key venv- --limit 20で、キャッシュが保存されているかを確認できます。

よくある間違い

  1. setup-pythonの後にPoetryをインストールする。cache: poetryを使うと、アクションがPoetryを見つけられずに失敗します。
  2. poetry.lockをコミットしない。この場合、キーに有効な情報がなくなります。
  3. 仮想環境のキーにPythonバージョンがない。イメージ更新後に、原因の分かりにくいimportエラーが発生します。
  4. poetry installに--no-interactionを付けない。CIで問題になることは稀ですが、付けておくと安心です。
  5. キャッシュを信頼できる情報源として扱う。何か不審な動作があった場合は、エントリを削除(gh cache delete <id>)して再構築してください。

スコープや削除の仕組みがこれらにどう影響するかは、GitHub Actionsのキャッシュとキャッシュの上限を参照してください。

よくある質問

.venvとPoetryのキャッシュディレクトリのどちらをキャッシュすべきですか?

.venvの方が速く、キャッシュディレクトリの方が安全です。正確なPythonバージョンとpoetry.lockのハッシュを含むキーで.venvを使用してください。

pipxがなくてもcache: poetryは動作しますか?

poetry が PATH 上にある必要があります。setup-python より前に実行されるのであれば、どのインストール方法でも構いません。

CI では Poetry の代わりに uv を使うべきでしょうか?

これはプロジェクトごとの判断です。インストールをより速くしたいだけであれば、pip のキャッシュにある uv の解説をご覧ください。

モノレポで Poetry をキャッシュするにはどうすればよいですか?

プロジェクトごとに cache-dependency-path を設定し、キーのプレフィックスも個別に指定してください。そうすることで、ある lockfile の変更が他のキャッシュを無効化することを防げます。

次のステップ

pytest の実行時間については、pytest の遅いテストをご覧ください。ほかに改善すべき点を確認するには、GitHub Actions を高速化する方法をお読みください。compiler.dev では、より高速なマシンでジョブを比較できる無料トライアル 200 分をご利用いただけます。詳しくは 料金をご覧ください。

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

無料で試す