Poetry-Abhängigkeiten in GitHub Actions cachen
Zuletzt aktualisiert am
Um Poetry in GitHub Actions zu cachen, installieren Sie Poetry vor actions/setup-python und setzen dann cache: poetry. setup-python cacht dann das virtualenv von Poetry, mit dem Schlüssel auf Basis von poetry.lock. Die Reihenfolge der Schritte wird häufig falsch gemacht und ist der erste Punkt, den Sie prüfen sollten, wenn der Cache-Schritt fehlschlägt.
Option 1: setup-python mit cache: poetry
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
Laut README von setup-python (Stand Oktober 2026) cacht cache: poetry die virtualenv-Verzeichnisse, eines für jedes Poetry-Projekt, das gefunden wird. Der Standardschlüssel bildet einen Hash über poetry.lock. Die Action führt Poetry aus, um diese Verzeichnisse zu finden, daher muss Poetry zuerst installiert sein. pipx ist auf den GitHub-gehosteten Ubuntu-Images vorinstalliert. Auf anderen Runnern installieren Sie zuerst pipx oder verwenden pip install poetry.
Verwenden Sie cache-dependency-path, wenn sich die Lock-Datei in einem Unterverzeichnis befindet:
- uses: actions/setup-python@v7
with:
python-version: "3.13"
cache: poetry
cache-dependency-path: services/api/poetry.lock
Option 2: explizites actions/cache mit einem virtualenv im Projekt
Poetry legt virtualenvs standardmäßig in einem gemeinsamen Verzeichnis ab (~/.cache/pypoetry/virtualenvs unter Linux) mit einem gehashten Namen. Wenn das venv als .venv im Projekt liegt, erhalten Sie einen festen Pfad zum Cachen.
- 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
Drei Details sind hier wichtig:
- Der Schlüssel enthält die exakte Python-Version.
steps.py.outputs.python-versionliefert die vollständige Version, zum Beispiel3.13.1. Ein virtualenv enthält Verweise auf den Interpreter, mit dem es erstellt wurde. Aktualisiert das Runner-Image Python, wäre ein unter einem alten Schlüssel wiederhergestelltes venv defekt. Die exakte Version im Schlüssel erzwingt einen Neuaufbau. poetry installläuft trotzdem. Bei einem Cache-Treffer findet es alles bereits installiert und ist in Sekunden fertig. Bei einer teilweisen Wiederherstellung überrestore-keysergänzt oder aktualisiert es nur, was sich geändert hat.- Setzen Sie
virtualenvs.in-projectvor dem Cache-Schritt. Andernfalls erstellt Poetry das venv an einem anderen Ort und.venvbleibt leer.
Option 3: nur den Download-Cache cachen
Wenn Sie kein venv cachen möchten, cachen Sie den Download-Cache von Poetry und lassen poetry install das venv jedes Mal neu aufbauen:
- uses: actions/cache@v6
with:
path: ~/.cache/pypoetry
key: poetry-${{ runner.os }}-${{ hashFiles('poetry.lock') }}
restore-keys: |
poetry-${{ runner.os }}-
Das ist sicherer, aber langsamer, weil Wheels bei jedem Lauf weiterhin entpackt werden. Mit poetry config cache-dir ermitteln Sie den tatsächlichen Pfad auf Ihrem Runner.
Was Sie cachen sollten und was nicht
| Eintrag | Cachen? | Hinweise |
|---|---|---|
Projektinternes .venv | Ja, mit Python-Version im Schlüssel | Schnellste Wiederherstellung |
~/.cache/pypoetry | Ja | Sicher, spart nur Downloads |
| Die Poetry-Installation selbst | Optional | pipx install poetry dauert nur Sekunden |
dist/-Build-Ausgabe | Nein | Wird pro Release neu gebaut |
Fixieren Sie die Poetry-Version (pipx install poetry==2.x), wenn Sie ein venv cachen. Ein Poetry-Upgrade kann den Aufbau der Umgebung verändern, und eine nicht fixierte Installation macht Ihren Schlüssel unvollständig.
So überprüfen Sie einen Cache-Treffer
- Suchen Sie in der setup-python- oder Cache-Schritt-Ausgabe nach
Cache restored from key: .... Bei einem Fehlschlag sehen SieCache not found for input keys: .... - In der Ausgabe von
poetry installgibt ein warmer LaufNo dependencies to install or updateaus. Ein kalter Lauf listet jedes Paket mitInstalling ...auf. - Bei explizitem
actions/cacheverzweigen Sie beim Debuggen über die Ausgabe:if: steps.cache.outputs.cache-hit != 'true'läuft nur bei einem Fehlschlag. gh cache list --key venv- --limit 20zeigt, ob Einträge gespeichert werden.
Häufige Fehler
- Poetry nach setup-python installieren. Mit
cache: poetryfindet die Action Poetry nicht und schlägt fehl. - Keine
poetry.lockcommitten. Der Schlüssel wird dann aus nichts Brauchbarem gebildet. - Python-Version fehlt im venv-Schlüssel. Führt nach einem Image-Update zu verwirrenden Import-Fehlern.
poetry installohne--no-interactionverwenden. In CI selten ein Problem, aber eine günstige Absicherung.- Den Cache als maßgebliche Quelle behandeln. Tritt etwas Ungewöhnliches auf, löschen Sie den Eintrag (
gh cache delete <id>) und bauen ihn neu auf.
Wie Geltungsbereich und Bereinigung all das beeinflussen, erfahren Sie unter Caching in GitHub Actions und Cache-Limits.
FAQ
Ist es besser, .venv oder das Poetry-Cache-Verzeichnis zu cachen?
.venv ist schneller, das Cache-Verzeichnis ist sicherer. Verwenden Sie .venv mit einem Schlüssel, der die exakte Python-Version und den Hash von poetry.lock enthält.
Funktioniert cache: poetry auch ohne pipx?
Dafür wird poetry im PATH benötigt. Jede Installationsmethode funktioniert, solange sie vor setup-python ausgeführt wird.
Sollte ich in der CI uv statt Poetry verwenden?
Das ist eine Projektentscheidung. Wenn Sie nur schnellere Installationen möchten, lesen Sie die uv-Hinweise unter Caching für pip.
Wie cache ich Poetry in einem Monorepo?
Geben Sie jedem Projekt einen eigenen cache-dependency-path und ein eigenes Schlüsselpräfix, damit Änderungen an einer Lock-Datei die anderen nicht ungültig machen.
Nächste Schritte
Zur Laufzeit von pytest lesen Sie langsame pytest-Tests. Welche weiteren Stellschrauben es gibt, erfahren Sie unter So beschleunigen Sie GitHub Actions. compiler.dev bietet Ihnen 200 kostenlose Testminuten, um Ihren Job auf einer schnelleren Maschine zu vergleichen; siehe Preise.
Verwandt
- Cargo- und Rust-Builds in GitHub Actions cachenCargo-Registry, Git-Abhängigkeiten und Target-Verzeichnis in GitHub Actions mit Swatinem/rust-cache oder actions/cache cachen, ohne aufgeblähte Caches.
- Go-Module und Build-Cache in GitHub Actions cachenGo-Module (GOMODCACHE) und Build-Cache (GOCACHE) in GitHub Actions mit setup-go oder actions/cache cachen. Keys, go.sum und Cache-Treffer prüfen.
- Gradle-Builds in GitHub Actions cachenGradle-Abhängigkeiten und Build-Cache in GitHub Actions mit gradle/actions/setup-gradle oder actions/cache cachen. Keys, PRs, Bereinigung, Checks.
- npm-Abhängigkeiten in GitHub Actions cachennpm-Abhängigkeiten in GitHub Actions cachen, mit setup-node oder actions/cache. Funktionierendes YAML, der richtige Key, warum nicht node_modules, und Treffer prüfen.