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.
| Cache | Lohnt sich das? | Warum |
|---|---|---|
| pip cache dir | Ja | Spart Downloads und lokale Wheel-Builds |
Eine virtuelle Umgebung (.venv) | Selten | An einen Python-Build und Pfad gebunden; bricht bei Minor-Upgrades |
~/.cache/pre-commit | Ja, separat | Hook-Umgebungen, Schlüssel aus .pre-commit-config.yaml |
.pytest_cache, .mypy_cache, .ruff_cache | Manchmal | Tool-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
- Der Schritt setup-python protokolliert
Cache restored from key: setup-python-Linux-...-pip-.... Ein Fehlschlag protokolliertCache not found. - In der Ausgabe von
pip installzeigen aus dem Cache wiederhergestellte PaketeUsing cached ...stattDownloading .... - Am Ende eines Jobs ohne Treffer gibt der Post-Schritt
Cache saved with key: ...aus. 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
- Kein Lockfile. Eine lose
requirements.txtohne fixierte Versionen führt dazu, dass der Schlüssel gleich bleibt, während sich die aufgelösten Versionen ändern. Fixieren Sie mitpip-compile,uv pip compileoder einem Lockfile. - Hashing einer nicht existierenden Datei. Mit
cache: pipund ohnerequirements.txtoderpyproject.tomlbricht setup-python mit einem Fehler ab. Setzen Siecache-dependency-path. - Ein Schlüssel für mehrere Python-Versionen. Nehmen Sie die Version in explizite Schlüssel auf; setup-python macht das bereits.
- Direktes Cachen von
site-packages. Dieselbe Fragilität wie beim Cachen einer venv. - 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.
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.