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をアップグレードすると環境の構成が変わることがあり、バージョンを固定しないとキーの情報が不完全になります。
キャッシュヒットの確認方法
- setup-pythonまたはcacheステップの出力で
Cache restored from key: ...を確認します。キャッシュが見つからない場合はCache not found for input keys: ...と表示されます。 poetry installの出力で、ウォーム実行時はNo dependencies to install or updateと表示されます。コールド実行時は、各パッケージがInstalling ...として一覧表示されます。- 明示的な
actions/cacheを使う場合は、デバッグ中に出力を条件分岐に使えます。if: steps.cache.outputs.cache-hit != 'true'は、キャッシュがヒットしなかった場合のみ実行されます。 gh cache list --key venv- --limit 20で、キャッシュが保存されているかを確認できます。
よくある間違い
- setup-pythonの後にPoetryをインストールする。
cache: poetryを使うと、アクションがPoetryを見つけられずに失敗します。 poetry.lockをコミットしない。この場合、キーに有効な情報がなくなります。- 仮想環境のキーにPythonバージョンがない。イメージ更新後に、原因の分かりにくいimportエラーが発生します。
poetry installに--no-interactionを付けない。CIで問題になることは稀ですが、付けておくと安心です。- キャッシュを信頼できる情報源として扱う。何か不審な動作があった場合は、エントリを削除(
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 分をご利用いただけます。詳しくは 料金をご覧ください。
関連記事
- 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 をキャッシュしない理由、キャッシュヒットの確認方法を解説します。