Kleine, schnelle, reproduzierbare Python-Docker-Images

Veröffentlicht

10. Oktober 2026

Autor

Faizan Nadeem

Die Grundlagen

Was ein Multi-Stage-Build tatsächlich tut

Ein Multi-Stage-Dockerfile hat mehr als eine FROM-Zeile, und jede beginnt eine neue, isolierte Build-Stage. Spätere Stages können selektiv COPY --from=<frühere Stage> spezifische Dateien aus dem Dateisystem einer früheren Stage kopieren, aber nichts sonst über diese frühere Stage – ihre installierten Pakete, ihre zwischengespeicherten Downloads, ihr Compiler-Toolchain – kommt mit, außer du kopierst es explizit. Das finale Image wird nur aus dem letzten FROM aufwärts gebaut, plus dem, was du mit COPY --from hereingezogen hast.

Dieser eine Mechanismus löst beide oben genannten Probleme auf einmal. Man erhält eine „Builder"-Stage, die groß und langsam sein darf – gcc installieren, Wheels kompilieren, einen vollständigen Dependency-Baum auflösen – und eine „Runtime"-Stage, die nur die fertigen, bereits gebauten Artefakte erhält: eine befüllte virtuelle Umgebung und deinen Anwendungscode. Der Compiler wird nie geshippt. Der Download-Cache des Package-Managers wird nie geshippt. Nur die Ausgabe.

Warum das wichtig ist, selbst wenn du dich nicht um Image-Größe kümmerst

Angriffsfläche. Ein Produktions-Container mit gcc, make und installierten apt-Paketlisten ist ein größeres Ziel als einer mit nur einem Python-Interpreter und deiner App. Build-Tooling aus dem Runtime-Image zu entfernen ist eine echte Sicherheitsverbesserung, keine bloße Diät.
Cold-Start-Zeit. Auf Lambda, Cloud Run und jedem autoskalierenden Kubernetes-Setup muss das Container-Image gezogen (und manchmal dekomprimiert) werden, bevor ein neues Replikat Traffic bedienen kann. Ein 180-MB-Image startet unter Scale-to-Zero-Bedingungen materiell schneller als ein 1,2-GB-Image.
CI-Minuten kosten Geld. Ein Dockerfile, das deinen gesamten Dependency-Baum neu baut, weil du eine Zeile Anwendungscode geändert hast, verbrennt bei jedem einzelnen Push CI-Zeit und Entwicklergeduld.

Die vollständige Architektur

┌─────────────────────┐        ┌──────────────────────┐
│   builder stage      │        │   runtime stage        │
│   FROM python:3.12    │        │   FROM python:3.12-slim │
│                       │  copy  │                        │
│  gcc, build-essential │ ─────► │  (no compiler)         │
│  uv sync → .venv/     │  .venv │  .venv/  (copied)       │
│  full source tree     │  app   │  app code only          │
└─────────────────────┘        └──────────────────────┘

Das Leitprinzip: Die Builder-Stage beantwortet „Was braucht es, um eine funktionierende virtuelle Umgebung und einen kompilierten Satz von Abhängigkeiten zu erstellen?" und die Runtime-Stage beantwortet „Was braucht es, um diese Umgebung auszuführen?" Das sind verschiedene Fragen mit verschiedenen Antworten, und sie in eine FROM-Zeile zu kollabieren ist die Grundursache sowohl für Aufblähung als auch für langsame Rebuilds.

Erläuterung der Core-Layer

1. Die Base-Image-Wahl

Was es ist: python:3.12 (das Standard-Debian-basierte Image), python:3.12-slim (ein abgespecktes Debian ohne die meisten Dev-Header und Docs) und python:3.12-alpine (musl-basiert, am kleinsten, aber eine andere C-Bibliothek) sind die drei realistischen Ausgangspunkte.

Warum es wichtig ist: slim ist fast immer der richtige Standard für die Runtime-Stage. Alpine sieht allein wegen der Größe attraktiv aus, aber musl libc bricht oder verlangsamt eine überraschende Anzahl kompilierter Python-Pakete (numpy, pandas, cryptography hatten alle über die Jahre echte Alpine-spezifische Probleme), und man kompiliert auf Alpine häufig aus dem Quellcode statt ein vorgefertigtes manylinux-Wheel zu installieren – was den Größenvorteil zunichte macht, indem es den Build langsamer macht und das Image in einigen Fällen nach Landung der kompilierten Artefakte gar nicht kleiner ist.

Produktionstipp: Verwende das vollständige python:3.12-Image (oder python:3.12-bookworm explizit für Reproduzierbarkeit) als Builder-Stage, wo du trotzdem gcc brauchst, und python:3.12-slim-bookworm als Runtime-Stage. Pinne den Debian-Codenamen, nicht nur die Python-Version – slim allein kann sich still auf eine neuere Debian-Release aktualisieren.

2. Abhängigkeiten mit `uv` statt `pip` installieren

Was es ist: uv ist ein Rust-basierter Python-Package-Manager und -Resolver, der in den meisten Workflows als Drop-in-Ersatz für pip und pip-tools dient und vom selben Team wie ruff (Astral) gebaut wurde.

Warum es wichtig ist: Dependency-Auflösung und Installation mit plain pip ist genuinlich einer der langsameren Teile eines Python-Image-Builds, besonders bei größeren Dependency-Bäumen. uv parallelisiert Downloads, verwendet einen globalen Cache, der nach Package-Hash geführt wird, sodass wiederholte Installationen über Projekte und Images hinweg nicht dasselbe Wheel erneut herunterladen, und löst Lockfiles eine Größenordnung schneller als pip-compile. In einem Docker-Build speziell kombiniert sich diese Geschwindigkeit mit BuildKit-Cache-Mounts (unten) dazu, eine From-Scratch-Dependency-Installation von Minuten auf Sekunden zu reduzieren bei warmem Cache.

Produktionstipp: Installiere mit uv sync --frozen --no-install-project gegen eine committed uv.lock-Datei, nicht uv pip install -r requirements.txt. --frozen verweigert es, das Lockfile im Container-Build still zu aktualisieren – wenn dein Lockfile und pyproject.toml auseinanderdriften, soll das in CI laut fehlschlagen, nicht einen anderen Dependency-Satz als den auflösen, den ein Entwickler lokal getestet hat.

3. BuildKit-Cache-Mounts für den Package-Cache

Was es ist: RUN --mount=type=cache,target=/root/.cache/uv weist BuildKit an, ein Verzeichnis über Builds hinweg zu persistieren, separat vom eigenen Layer-Cache des Images – die Inhalte leben in einem Docker-verwalteten Cache-Volume, nicht in einem Image-Layer, sodass sie das finale Image nie aufblähen, aber tatsächlich zwischen Builds auf derselben Maschine (und über ein geteiltes BuildKit-Cache-Backend in CI) überleben.

Warum es wichtig ist: Ohne das startet jeder docker build – sogar mit einem Treffer im regulären Layer-Cache von Docker – uvs eigenen Download-Cache leer innerhalb der Ausführung dieser Layer. Mit ihm liegt eine Abhängigkeit, die in Build #1 heruntergeladen wurde, bereits beim BuildKit-Cache-Mount in Build #50, selbst wenn der Layer darüber sich geändert hat und einen Neustart des Install-Schritts erzwang.

Produktionstipp: Verwende beide Caching-Mechanismen zusammen, nicht einen statt des anderen – Dockers Layer-Cache um den Install-Schritt vollständig zu überspringen wenn sich nichts geändert hat, und den BuildKit-Cache-Mount um den Install-Schritt selbst bei den seltenen Gelegenheiten schnell zu machen, wenn er tatsächlich neu ausgeführt werden muss.

4. Instruktionen für echte Cache-Treffer ordnen

Was es ist: Dockers Layer-Cache invalidiert einen Layer und jeden Layer danach, sobald sich irgendeine frühere COPY- oder RUN-Anweisung im Dockerfile ändert. Das bedeutet, dass die Instruktionsreihenfolge nicht kosmetisch ist – sie bestimmt direkt, ob das Bearbeiten von app/routes.py eine vollständige Dependency-Neuinstallation auslöst oder nicht.

Warum es wichtig ist: Wenn du COPY . . vor dem Ausführen von uv sync machst, invalidiert jede Dateiänderung – einschließlich ein einzeiliger Kommentar in deinem Anwendungscode – den Dependency-Install-Layer, und du baust deinen gesamten Dependency-Baum bei jeder einzelnen Code-Änderung neu. Das ist der einzige häufigste Grund, warum Teams glauben, Docker-Builds für Python sind inherent langsam.

Produktionstipp: Kopiere nur pyproject.toml und uv.lock zuerst, führe die Installation durch, und kopiere dann erst den Rest des Source Trees. Dependency-Änderungen sind weit seltener als Code-Änderungen, sodass diese Reihenfolge bedeutet, dass der teure Layer nur dann neu läuft, wenn er es tatsächlich muss.

5. Nicht-Root-Benutzer und minimale Runtime-Oberfläche

Was es ist: Standardmäßig läuft ein Container-Prozess als Root innerhalb des Containers, sofern das Image nicht explizit einen Nicht-Root-Benutzer mit USER erstellt und wechselt.

Warum es wichtig ist: Als Root innerhalb eines Containers zu laufen ist nicht äquivalent zu Root auf dem Host, aber es ist immer noch eine unnötige Privilege-Escalation-Oberfläche, wenn der Prozess jemals kompromittiert wird – und mehrere verwaltete Plattformen (Cloud Run mit bestimmten Konfigurationen, einige Kubernetes Pod Security Standards) warnen vor oder lehnen direkt Root-Benutzer-Container ab.

Produktionstipp: Erstelle den Benutzer in der Runtime-Stage, nicht der Builder-Stage, und chown das App-Verzeichnis explizit an ihn – COPY --chown=appuser:appuser in der letzten COPY-Anweisung erledigt das in einem Schritt ohne einen zusätzlichen RUN chown-Layer.

Durchgehende Erklärung

Verfolge eine Code-Änderung von git push zu einem laufenden Container:

Entwickler bearbeitet app/main.py und pushed. pyproject.toml und uv.lock sind unverändert.
CI führt docker build aus. BuildKit hasht die Eingaben jeder Anweisung. Die COPY pyproject.toml uv.lock ./ und RUN uv sync-Layer hashen identisch zum letzten Build – Cache-Treffer, beide Layer werden vollständig übersprungen.
Der COPY . .-Layer übernimmt das geänderte app/main.py und invalidiert von diesem Punkt vorwärts – aber das ist die einzige Arbeit, die erledigt werden musste.
Die Runtime-Stage startet neu von python:3.12-slim, und COPY --from=builder /app/.venv /app/.venv zieht die bereits gebaute virtuelle Umgebung herein – keine Neuinstallation findet in dieser Stage statt, weil der Builder das bereits erledigt hat.
Das finale Image wird getaggt und gepusht. Weil die Runtime-Stage nie gcc oder den uv-Cache drin hatte, ist das Image, das geshippt wird, nur der Interpreter, das venv und der App-Code.
Das Deploy löst einen Pull auf der Zielplattform aus. Ein kleineres Image wird schneller gezogen, und wenn die Plattform Scale-to-Zero ist (Cloud Run, Lambda-Container-Images), sitzt diese Pull-Zeit direkt in der benutzersichtbaren Cold-Start-Zeit.

Sonderfälle

Native/kompilierte Abhängigkeiten (psycopg2, numpy, cryptography, pillow). Diese brauchen echte C-Bibliotheken zum Kompilieren (libpq-dev für psycopg2 zum Beispiel) und oft einen Compiler. Installiere die -dev-Header und build-essential nur in der Builder-Stage. Wenn die Runtime-Stage die shared library zur Laufzeit braucht (nicht nur zur Build-Zeit – libpq ist ein häufiges Beispiel), installiere das Nicht-Dev-Runtime-Paket (libpq5, nicht libpq-dev) auch in der Runtime-Stage; das kompilierte Python-Wheel linkt dynamisch dagegen. Diesen Schritt zu überspringen produziert einen funktionierenden Build und einen sofortigen ImportError oder Segfault beim Container-Start, was beim ersten Auftreten eine frustrierende Lücke zum Debuggen ist.

Private Package-Indexes. Wenn uv sync einen privaten PyPI-Spiegel oder eine Git-basierte Abhängigkeit hinter Auth erreichen muss, übergebe die Anmeldedaten als Build-Secret mit --mount=type=secret, niemals als ARG oder ENV – Build-Args landen in der Image-History und sind mit docker history wiederherstellbar, selbst für Zwischen-Stages, die nicht geshippt werden.

Speziell eine FastAPI-App deployen. Wenn du einen FastAPI-Service containerisierst, ist das Dockerfile-Muster hier identisch, aber wo du main.py, deine Router und deine Dependency-Injection-Verdrahtung innerhalb des Images platzierst, ist wichtig dafür, wie sauber dieses Copy-Order-Caching funktioniert – eine Projektstruktur wie die im Guide zur Strukturierung eines FastAPI-Projekts hält Anwendungscode sauber von Konfiguration getrennt, genau die Trennung, die dieses Dockerfile-Muster ausnutzen will.

Multi-Plattform-Builds (linux/amd64 + linux/arm64). docker buildx build --platform linux/amd64,linux/arm64 baut beide in einem Durchgang, aber kompilierte Abhängigkeiten ohne vorgefertigte manylinux_aarch64-Wheels kompilieren aus dem Quellcode auf dem arm64-Zweig, was in CI bedeutsam langsamer ist. Überprüfe die Wheel-Verfügbarkeit deines Dependency-Baums, bevor du davon ausgehst, dass Multi-Plattform-Builds gratis sind.

Skalierung & Produktionsherausforderungen

CI-Cache persistiert standardmäßig nicht zwischen flüchtigen Runners. BuildKit-Cache-Mounts sind lokal auf die Maschine, auf der der Build läuft. Auf GitHub Actions oder irgendeinem flüchtigen-Runner-CI ist dieser Cache beim Start des nächsten Laufs weg, sofern du ihn nicht explizit exportierst – docker buildx build --cache-to=type=registry,ref=<repo>:buildcache --cache-from=type=registry,ref=<repo>:buildcache schiebt den Cache zu einer Registry, damit der nächste Lauf, selbst auf einem brandneuen Runner, ihn zurückziehen kann.

Image-Größe vs. Layer-Anzahl ist bei Scale ein echter Kompromiss. Das Kombinieren von RUN-Anweisungen mit && reduziert die Layer-Anzahl, was die Pull-Zeit leicht verbessert, bedeutet aber auch, dass eine Änderung irgendwo in dieser kombinierten Anweisung das Ganze invalidiert. Für ein Dockerfile, das dutzendmal täglich in CI gebaut wird, ist mehr, kleinere, gut geordnete Layer gegenüber weniger kombinierten normalerweise der bessere Kompromiss.

Reproduzierbarkeit über Builds hinweg. Pinne dein Base-Image per Digest (python:3.12-slim-bookworm@sha256:...), nicht nur per Tag, für alles, das du Bit-für-Bit reproduzierbar brauchst – Tags sind veränderlich und Debian-Sicherheits-Patches rollen in slim-Images ohne eine Versionsänderung, die du bemerken würdest.

Code-Beispiele

Ein vollständiges Multi-Stage-Dockerfile für einen FastAPI-Service, mit uv und BuildKit-Cache-Mounts:

# syntax=docker/dockerfile:1

FROM python:3.12-bookworm AS builder

RUN apt-get update && apt-get install -y --no-install-recommends \
        build-essential \
        libpq-dev \
    && rm -rf /var/lib/apt/lists/*

COPY --from=ghcr.io/astral-sh/uv:0.5 /uv /usr/local/bin/uv

WORKDIR /app

# Copy only dependency manifests first, so this layer (and the
# expensive install below) only invalidates when they actually change.
COPY pyproject.toml uv.lock ./

RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-install-project --no-dev

# Now copy the rest of the source and finish the install (this
# installs the project itself as an editable/non-editable package).
COPY . .
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev


FROM python:3.12-slim-bookworm AS runtime

RUN apt-get update && apt-get install -y --no-install-recommends \
        libpq5 \
    && rm -rf /var/lib/apt/lists/* \
    && useradd --create-home --uid 1000 appuser

WORKDIR /app

COPY --from=builder --chown=appuser:appuser /app/.venv /app/.venv
COPY --from=builder --chown=appuser:appuser /app /app

USER appuser
ENV PATH="/app/.venv/bin:$PATH"
ENV PYTHONUNBUFFERED=1

EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Mit dem Registry-Cache für CI bauen:

docker buildx build \
    --platform linux/amd64 \
    --cache-from type=registry,ref=myregistry.example.com/myapp:buildcache \
    --cache-to type=registry,ref=myregistry.example.com/myapp:buildcache,mode=max \
    -t myregistry.example.com/myapp:latest \
    --push .

Prüfen, was tatsächlich geshippt wurde:

docker images myregistry.example.com/myapp:latest
docker history myregistry.example.com/myapp:latest --no-trunc

Häufige Fallstricke

Fehler: COPY . . vor der Installation von Abhängigkeiten. Das ist die einzige häufigste Ursache dafür, dass „warum dauert mein Docker-Build vier Minuten für eine einzeilige Änderung." Lösung: zuerst pyproject.toml/uv.lock kopieren, installieren, dann den Rest kopieren.

Fehler: Compiler und Header der Builder-Stage in der Produktion shippen. Ein einzelnes FROM ohne separate Runtime-Stage bedeutet, dass gcc, build-essential und jedes -dev-Paket, das du zum Kompilieren einer nativen Extension gebraucht hast, im deployed Image landen. Lösung: in Builder- und Runtime-Stage aufteilen; nur das fertige .venv und App-Code rüberkopieren.

Fehler: Dev-Abhängigkeiten im Produktions-Image installieren. uv sync ohne --no-dev installiert dein Test-Framework, Linter und Debugger in das Runtime-Image. Lösung: immer --no-dev (oder die äquivalente Extras-Ausschluss-Option) für das finale Produktions-Install übergeben.

Fehler: Die Runtime-Shared-Library für eine kompilierte Abhängigkeit vergessen. Das Wheel kompiliert und installiert einwandfrei in der Builder-Stage, dann stürzt die App beim Import in der Runtime-Stage ab, weil libpq.so nicht vorhanden ist. Lösung: identifiziere, welche Runtime-.so-Dateien eine kompilierte Abhängigkeit braucht, und installiere das entsprechende Nicht-Dev-Systempaket auch in der Runtime-Stage.

Fehler: Images nur :latest taggen, ohne Digest-Pinning irgendwo. Das macht einen „warum verhält sich die Produktion plötzlich anders"-Vorfall unmöglich zu bisektieren. Lösung: Base-Images per Digest für Reproduzierbarkeit pinnen, und gebaute Images zusätzlich zu einem beweglichen :latest-Tag mit dem Git-SHA taggen.

Best Practices für die Produktion

Trenne immer Build-Tooling von Runtime. Wenn ein Paket gcc zum Installieren braucht, gehört dieses gcc in eine Stage, die nie geshippt wird.
Ordne Dockerfile-Instruktionen von am seltensten bis am häufigsten geändert. Dependency-Manifests vor Source-Code, Source-Code vor allem Umgebungsspezifischen.
Verwende uv mit --frozen und einer committed Lockfile. Reproduzierbare Installs sind in einem Container-Build wichtiger als fast überall sonst, da es das eine Artefakt ist, das in CI, Staging und Produktion identisch verhalten muss.
Richte einen Registry-backed BuildKit-Cache in CI ein. Lokale Cache-Mounts sind auf flüchtigen Runners ohne das wertlos.
Laufe als Nicht-Root-Benutzer und pinne Base-Images per Digest. Beides ist fast kostenlos und reduziert die Angriffsfläche und das Nicht-Reproduzierbarkeitsrisiko deines Images bedeutsam.

Fazit

Klein, schnell, reproduzierbar – das sind keine drei separate Ziele, die gegeneinander abgewogen werden müssen – sie ergeben sich größtenteils aus denselben wenigen Entscheidungen: was die App baut von dem trennen, was sie ausführt, dein Dockerfile so ordnen, dass der Cache dich tatsächlich schützt, und uv und BuildKit-Cache-Mounts die Parallelisierungs- und Caching-Arbeit machen lassen, die pip nie schnell zu machen konzipiert war. Das erfordert keine exotischen Werkzeuge oder ein Rewrite; es ist eine Dockerfile-Umstrukturierung, die du an einem Nachmittag vornehmen kannst, und die Dividende zeigt sich bei jedem einzelnen Build danach, nicht nur beim ersten.

Wenn dein aktuelles Python-Image immer noch ein einzelnes FROM python:3.12 mit pip install -r requirements.txt irgendwo in der Mitte eines COPY . .-Blocks ist, ist das die eine Zeile, die es zuerst wert ist zu beheben – alles andere in diesem Beitrag folgt daraus, das auseinanderzuteilen.