Zum Inhalt springen

pip-Abhängigkeiten in GitHub Actions cachen

Zuletzt aktualisiert am

Um pip in GitHub Actions zu cachen, setzen Sie cache: pip bei actions/setup-python. Dabei wird der globale Download-Cache von pip gespeichert, mit dem Schlüssel aus Ihren Requirements-Dateien. Wenn Sie auf uv umstellen können, cacht astral-sh/setup-uv seinen eigenen Speicher und installiert deutlich schneller. Beide Varianten finden Sie unten.

Option 1: Eingebauter Cache von 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

Laut README von setup-python (Stand Oktober 2026) cacht cache: pip das globale pip-Cache-Verzeichnis. Standardmäßig wird als Schlüssel ein Hash aus requirements.txt oder pyproject.toml im Repository-Stammverzeichnis gebildet. Wenn Sie mehrere Requirements-Dateien haben, geben Sie diese explizit an:

- uses: actions/setup-python@v7
  with:
    python-version: "3.13"
    cache: pip
    cache-dependency-path: |
      requirements.txt
      requirements-dev.txt

Caching ist nur aktiv, wenn Sie cache setzen. Der Schlüssel enthält außerdem die Python-Version und das Betriebssystem, daher erstellt eine Matrix für jede Kombination einen eigenen Eintrag.

Option 2: explizites 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 liefert den richtigen Pfad für das jeweilige Betriebssystem (unter Linux ~/.cache/pip). Die Python-Version gehört in den Schlüssel, weil kompilierte Wheels an den Interpreter gebunden sind.

Was pip tatsächlich cacht

pip speichert heruntergeladene Wheels und, wenn ein Paket aus dem Quellcode gebaut wird, das dabei erzeugte Wheel. Ein Cache-Treffer bei einem reinen Quellpaket, etwa einer älteren C-Erweiterung, spart mehr als den Download: Der Kompilierungsschritt entfällt.

CacheLohnt sich das?Warum
pip cache dirJaSpart Downloads und lokale Wheel-Builds
Eine virtuelle Umgebung (.venv)SeltenAn einen Python-Build und Pfad gebunden; bricht bei Minor-Upgrades
~/.cache/pre-commitJa, separatHook-Umgebungen, Schlüssel aus .pre-commit-config.yaml
.pytest_cache, .mypy_cache, .ruff_cacheManchmalTool-Caches, keine Abhängigkeiten

Eine ganze virtuelle Umgebung zu cachen kann schneller wirken, weil nichts installiert werden muss. Das ist jedoch fragil: Die venv enthält absolute Pfade und Verweise auf den Interpreter, daher kann ein Python-Patch-Release im Runner-Image eine defekte Umgebung hinterlassen. Wenn Sie diese Geschwindigkeit möchten, verwenden Sie Poetry mit venvs im Projektverzeichnis, geschlüsselt nach Lockfile und Python-Version, oder nutzen Sie uv.

Option 3: uv

uv ist ein schneller Drop-in-Installer von Astral. Die Setup-Action verwaltet den Cache für Sie.

- 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

Laut README von setup-uv (Stand Oktober 2026) ist enable-cache standardmäßig auf auto gesetzt, wodurch Caching auf GitHub-gehosteten Runnern aktiviert und auf selbst gehosteten deaktiviert wird. Auf selbst gehosteten Runnern, auch bei compiler.dev, setzen Sie enable-cache: true ausdrücklich. setup-uv installiert Ihr Projekt nicht; Sie führen weiterhin uv sync aus. Für einen pip-ähnlichen Workflow nutzt uv pip install -r requirements.txt denselben Cache.

So überprüfen Sie einen Cache-Treffer

  1. Der Schritt setup-python protokolliert Cache restored from key: setup-python-Linux-...-pip-.... Ein Fehlschlag protokolliert Cache not found.
  2. In der Ausgabe von pip install zeigen aus dem Cache wiederhergestellte Pakete Using cached ... statt Downloading ....
  3. Am Ende eines Jobs ohne Treffer gibt der Post-Schritt Cache saved with key: ... aus.
  4. gh cache list --key pip- --limit 20 (oder --key setup-python) listet die Einträge mit Größe und letzter Nutzung auf.

Häufige Fehler

  1. Kein Lockfile. Eine lose requirements.txt ohne fixierte Versionen führt dazu, dass der Schlüssel gleich bleibt, während sich die aufgelösten Versionen ändern. Fixieren Sie mit pip-compile, uv pip compile oder einem Lockfile.
  2. Hashing einer nicht existierenden Datei. Mit cache: pip und ohne requirements.txt oder pyproject.toml bricht setup-python mit einem Fehler ab. Setzen Sie cache-dependency-path.
  3. Ein Schlüssel für mehrere Python-Versionen. Nehmen Sie die Version in explizite Schlüssel auf; setup-python macht das bereits.
  4. Direktes Cachen von site-packages. Dieselbe Fragilität wie beim Cachen einer venv.
  5. Nur auf PRs speichern. Die Scope-Regeln bedeuten, dass ein PR-Cache für andere PRs nicht sichtbar ist. Siehe Caching in GitHub Actions.

Langsame Testsuiten sind ein anderes Problem als langsame Installationen; siehe pytest langsame Tests und Django auf GitHub Actions beschleunigen.

Größe und Limits

pip-Caches sind meist 100 MB bis 1 GB groß. Data-Science-Stacks (torch, CUDA-Wheels) können jeweils mehrere GB belegen und füllen das Repository-Kontingent von 10 GB schnell. Siehe Cache-Limits. Ist ein einzelnes Wheel sehr groß, prüfen Sie, ob der Download wirklich der Engpass ist.

FAQ

Soll ich site-packages oder eine virtuelle Umgebung cachen?

In der Regel nein. Cachen Sie das Download-Verzeichnis von pip oder nutzen Sie uv. Ein venv-Cache ist nur dann sicher, wenn der Schlüssel die exakte Python-Version und den Hash des Lockfiles enthält.

Wie cache ich pip für mehrere Requirements-Dateien?

Übergeben Sie sie alle an cache-dependency-path, jeweils eine pro Zeile.

Ist uv auch nur für CI sicher einsetzbar?

uv liest die Standarddateien requirements.txt und pyproject.toml. Probieren Sie zuerst uv pip install -r requirements.txt aus, dafür ändert sich nur eine Zeile.

Warum wird mein pip-Cache auf einem neuen Branch nie genutzt?

Ein neuer Branch kann seinen eigenen Cache und den Cache des Default-Branches lesen. Wenn main nie einen Cache speichert, gibt es nichts wiederherzustellen.

Nächste Schritte

Verwenden Sie Poetry? Lesen Sie Caching von Poetry in GitHub Actions. Einen Überblick über das Ganze finden Sie unter so beschleunigen Sie GitHub Actions. compiler.dev führt denselben Job auf 8-vCPU-Maschinen für $0.008 pro Minute aus; Details finden Sie unter Preise.

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

Kostenlos testen