Zum Inhalt springen

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-version liefert die vollständige Version, zum Beispiel 3.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 install läuft trotzdem. Bei einem Cache-Treffer findet es alles bereits installiert und ist in Sekunden fertig. Bei einer teilweisen Wiederherstellung über restore-keys ergänzt oder aktualisiert es nur, was sich geändert hat.
  • Setzen Sie virtualenvs.in-project vor dem Cache-Schritt. Andernfalls erstellt Poetry das venv an einem anderen Ort und .venv bleibt 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

EintragCachen?Hinweise
Projektinternes .venvJa, mit Python-Version im SchlüsselSchnellste Wiederherstellung
~/.cache/pypoetryJaSicher, spart nur Downloads
Die Poetry-Installation selbstOptionalpipx install poetry dauert nur Sekunden
dist/-Build-AusgabeNeinWird 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

  1. Suchen Sie in der setup-python- oder Cache-Schritt-Ausgabe nach Cache restored from key: .... Bei einem Fehlschlag sehen Sie Cache not found for input keys: ....
  2. In der Ausgabe von poetry install gibt ein warmer Lauf No dependencies to install or update aus. Ein kalter Lauf listet jedes Paket mit Installing ... auf.
  3. Bei explizitem actions/cache verzweigen Sie beim Debuggen über die Ausgabe: if: steps.cache.outputs.cache-hit != 'true' läuft nur bei einem Fehlschlag.
  4. gh cache list --key venv- --limit 20 zeigt, ob Einträge gespeichert werden.

Häufige Fehler

  1. Poetry nach setup-python installieren. Mit cache: poetry findet die Action Poetry nicht und schlägt fehl.
  2. Keine poetry.lock committen. Der Schlüssel wird dann aus nichts Brauchbarem gebildet.
  3. Python-Version fehlt im venv-Schlüssel. Führt nach einem Image-Update zu verwirrenden Import-Fehlern.
  4. poetry install ohne --no-interaction verwenden. In CI selten ein Problem, aber eine günstige Absicherung.
  5. 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.

Diese pytest-Suite auf compiler.dev ausführen Keine Karte nötig · 200 kostenlose Minuten

Kostenlos testen