Docker COPY: Mehrere Dateien in einer Layer kopieren (Dockerfile-Guide)

Hinweis: Diese Anleitung enthält Referral-Links. Wenn du darüber kaufst, erhalte ich möglicherweise eine Provision – ohne zusätzliche Kosten für dich.

Wenn du Docker-Images baust, musst du oft mehrere Dateien auf einmal kopieren. Docker COPY erlaubt dir, mehrere Quellen in einer Anweisung aufzulisten – und diese Anweisung erzeugt eine einzige Filesystem-Layer für alle:

COPY file1.txt file2.txt /app/files/

Das kopiert sowohl file1.txt als auch file2.txt aus dem Build-Context nach /app/files/ im Image. Eine Anweisung, eine Layer. Dateien zu gruppieren, die sich gemeinsam ändern, verhindert, dass der Build-Cache aus unzusammenhängenden Gründen bricht – und hält das Dockerfile kürzer.

Die Flag-Oberfläche ist gewachsen, seit dieser Artikel zuerst online ging: COPY --parents und COPY --exclude sind jetzt stabil (Dockerfile-Syntax 1.20 und 1.19), und rekursive **-Globs sind offiziell dokumentiert. Dieser Guide behandelt die Multi-Source-Syntax, die Wildcard-Regeln und die BuildKit-Flags, die sich lohnen – plus wie du verifizierst, dass deine Layer so aussehen, wie du denkst.

Ein paar andere Docker-Artikel, die du nützlich finden könntest:

• Add Users to a Docker Container
• Install Docker & Docker Compose on Ubuntu ARM
• Redirect Docker Logs to a Single File
• ARG and ENV Variables in Docker and Dockerfiles

Was du brauchst

Alles in dieser Anleitung läuft auf einer lokalen Docker-Installation oder einer kleinen Build-Maschine. Keine kostenpflichtigen Dienste.

Die COPY-Anweisung zum Kopieren von Dateien in einem Dockerfile nutzen

COPY überträgt Dateien aus deinem Build-Context (dem Verzeichnis, aus dem du docker build ausführst, oder dem Context, den du explizit übergibst) in das Image-Filesystem.

Ein hartes Limit im Hinterkopf: COPY kann keine Dateien außerhalb des Build-Context lesen. Wenn du etwas brauchst, das eine Ebene höher liegt, strukturiere deinen Context um oder lass CI einen zusammenstellen.

Basis-Syntax

COPY <src> <dest>

• <src>: Datei(en) oder Verzeichnis im Build-Context
• <dest>: Zielpfad im Image (wird angelegt, falls nicht vorhanden)

Mit einer einzigen Quelle kannst du eine Datei beim Kopieren umbenennen (COPY app.js /usr/local/bin/start.js). Mit mehreren Quellen geht das nicht.

Fehlerfälle, die man von vornherein kennen sollte:

• Zwei oder mehr Quellen und ein Ziel ohne abschließenden / → Build-Fehler oder eine einzige verstümmelte Datei am Ziel
• Quellpfad außerhalb des Build-Context → „file not found”, während Docker den Context überträgt, bevor überhaupt eine Layer gebaut wurde

Typische Anwendungsfälle

Eine einzelne Datei kopieren:

COPY app.js /app/

Ein ganzes Verzeichnis kopieren (zum Beispiel, wenn du ein Dockerfile für eine Python-App baust):

COPY src/ /app/src/

Mehrere bestimmte Dateien kopieren:

COPY file1.txt file2.txt config.json /app/

Dateien mit Wildcards kopieren:

COPY *.txt /app/

Das letzte kopiert passende .txt-Dateien aus der Context-Root nach /app/.

Eine Sache, die man nicht verwechseln sollte: Patterns werden von Docker ausgewertet (Go filepath.Match plus **), nicht von deiner Shell. Erwarte kein Bash-Globbing-Verhalten.

Mehrere Dateien in einer COPY-Anweisung kopieren (eine Layer)

Das ist der Kernmechanismus: Jede COPY-Anweisung erzeugt eine Filesystem-Layer, egal ob sie eine Datei oder zwanzig kopiert. Du kannst so viele Quellen auflisten, wie du willst, und sie landen alle in einer Layer:

COPY file1.txt file2.txt config.json /app/
COPY *.csv /data/
COPY src/ /code/

Was hier zählt:

• Bei mehreren Quellen muss das Ziel ein Verzeichnis sein (mit / abschließen)
• Gruppiere Dateien, die sich gemeinsam ändern: Configs mit Configs, Scripts mit Scripts
• Wenn sich eine Datei in einer gruppierten COPY ändert, wird der Cache für diese ganze Layer invalidiert und jede Datei darin wird erneut kopiert
• Weniger COPY-Zeilen bedeuten weniger Layer, aber der eigentliche Gewinn ist das Cache-Verhalten, nicht die Layer-Anzahl. Layer sind billige Metadaten; ein gebrochener Cache kostet dich Rebuild-Zeit

Diagramm, das 3 getrennte COPY-Anweisungen vergleicht, die 3 Layer erzeugen, von denen nur die geänderte neu gebaut wird, mit 1 gruppierten COPY-Anweisung, die 1 Layer erzeugt, die komplett neu gebaut wird, sobald sich eine Datei ändert

Achtung: Dateinamens-Kollisionen werden still überschrieben

Fixes, in der Reihenfolge ihrer Empfehlung:

1. Nutze COPY --parents, damit relative Pfade erhalten bleiben und nichts kollidieren kann
2. Kopiere jeden Satz in sein eigenes Zielverzeichnis
3. Liste Dateien explizit auf und benenne beim Kopieren um, wenn zwei Namen nebeneinander bestehen müssen

Wildcards mit Docker COPY: *, ?, ** und --exclude

Wildcards lassen dich jede Datei kopieren, die auf ein Pattern passt, in einer Anweisung. Dockerfile-Globbing ist nah an dem, was du kennst – mit ein paar Unterschieden, die man sich merken sollte.

Wildcard-Patterns, die funktionieren

** ist echt. Die offizielle Dockerfile-Referenz dokumentiert rekursives Matching über Verzeichnisebenen hinweg. Das kanonische Beispiel paart es mit --parents, damit die Verzeichnisstruktur das Kopieren überlebt:

# syntax=docker/dockerfile:1

FROM scratch
COPY --parents ./src/**/*.txt /parents/
# /parents/src/a.txt
# /parents/src/x/b.txt
# /parents/src/x/y/c.txt

Ein Ehrlichkeits-Hinweis: Die Docs demonstrieren ** innerhalb der --parents-Beispiele. Schlichtes COPY src/**/*.ts /out/ ohne --parents wird geflattet, und ich würde es mit einem Build verifizieren, bevor ich mich auf den exakten Match-Satz verlasse. Wenn die Struktur ohnehin zählt, greif zu --parents.

COPY –exclude: Dateien überspringen ohne .dockerignore zu bearbeiten

# syntax=docker/dockerfile:1

# Everything matching hom* except *.txt
COPY --exclude=*.txt hom* /mydir/

# Stack exclusions
COPY --exclude=*.txt --exclude=*.md hom* /mydir/

# The precise answer to "copy my sources but skip tests"
COPY --exclude=*.test.ts --exclude=fixtures/** src/**/*.ts /app/

Wann --exclude statt .dockerignore:

• --exclude gilt für eine einzelne Anweisung. Nutze es, wenn nur ein COPY etwas überspringen soll und der Rest des Builds diese Dateien im Context noch braucht.
• .dockerignore gilt für den ganzen Context. Nutze es, um Müll komplett aus dem Build-Transfer rauszuhalten (Logs, .git, node_modules), damit jeder Schritt schneller wird.

Was immer noch nicht unterstützt wird

COPY config.json config.yml config.yaml /app/config/

COPY --exclude=*.test.ts --exclude=fixtures/** src/**/*.ts /app/

COPY config/ /app/config/

Im Zweifel kopiere das Verzeichnis und lass .dockerignore ausschließen, was du nicht willst. Das ist für das Caching vorhersehbarer als ein cleverer Glob.

COPY –parents: die Verzeichnisstruktur erhalten

COPY --parents (stabil seit Dockerfile-Syntax 1.20) kopiert Quellen und behält dabei ihre relative Verzeichnisstruktur unter dem Ziel bei. Das ist das Flag, das du willst, wenn Dateien aus verschachtelten Verzeichnissen in passenden verschachtelten Pfaden landen müssen – und es eliminiert Basename-Kollisionen von Haus aus.

# syntax=docker/dockerfile:1

COPY --parents src/utils/*.ts src/components/*.ts /app/
# /app/src/utils/...
# /app/src/components/...

Zwei Semantiken, die man kennen sollte:

1. Der ./-Marker begrenzt, welche Eltern erhalten bleiben (dieselbe Idee wie rsync --relative). Alles vor dem Marker fällt aus dem Zielpfad heraus:

COPY --parents ./x/./y/*.txt /parents/
# /parents/y/a.txt   (x/ is not preserved)

2. Es paart sich mit --from in Multi-Stage-Builds, wo Quellpfade absolut sind und du meist nur das Ende des Pfades willst:

# syntax=docker/dockerfile:1

FROM build AS build
# ... produces /out/app/bin/ ...

FROM gcr.io/distroless/static
COPY --from=build --parents /out/./app/bin/ /app/
# /app/bin/... only

Diagramm des COPY –parents-Pfad-Mappings: ohne den ./-Marker bleibt der volle relative Pfad src/utils/a.ts unter /parents/ erhalten, mit dem ./-Marker bleiben nur die Verzeichnisse nach dem Marker erhalten

Stichprobe nach einem Rebuild: docker history <image> sollte einen COPY-Schritt mit der erwarteten Größe zeigen, und docker run --rm <image> ls -R /parents (oder find) sollte die Pfade zeigen, die du beabsichtigt hast.

BuildKit-COPY-Flags und Dockerfile-Syntax-Versionen

Du wirst alte Ratschläge über „Docker Engine 25+” für einige dieser Flags sehen. Das ist die falsche Achse. Was ein Dockerfile-Feature freischaltet, ist die Dockerfile-Syntax-Version, nicht die Engine-Version. Die Parser-Direktive oben in deinem Dockerfile zieht ein Frontend herein, das die neueren Flags versteht:

# syntax=docker/dockerfile:1

FROM node:22-alpine
# ... rest of the Dockerfile

BuildKit ist seit Docker Engine 23.0 der Default-Builder, und der Legacy-Builder ist deprecated. BuildKit ist an diesem Punkt der einzige unterstützte Pfad.

Mindest-Syntax-Versionen

COPY –link: unabhängige Layer und Fallstricke

--link kopiert die Quellen in ein leeres Zielverzeichnis und linkt das oben auf den vorherigen Image-Zustand. Effektiv baut es FROM scratch; COPY ... und merged das Ergebnis. Drei Konsequenzen folgen.

Die Copy-Layer bekommt Cache-Unabhängigkeit: Sie hängt nicht mehr von Eltern-Layern ab, sodass das Ändern des Basis-Images oder einer früheren Anweisung sie nicht invalidiert. Die Docs sagen es klar: Dateien „remain independent on their own layer and don’t get invalidated when commands on previous layers are changed.” Das ermöglicht das Rebasen eines Images auf eine neuere Basis, ohne die Copy-Schritte neu zu bauen. Der Trade-off ist das Flattening: Mehrere Quellen landen flach in diesem leeren Verzeichnis, also kombiniere --link mit --parents, wenn du Struktur brauchst. Die Referenz listet außerdem ein paar Caveats: Beim Kopieren in ein Unterverzeichnis kopiert --link immer von der Filesystem-Root; Verzeichnis-Permissions werden überschrieben (nutze --chmod, wenn du ein permissives Verzeichnis wie /tmp brauchst); und die Docs empfehlen --link, „unless you rely on symlink behavior in the destination.”

Cache-sicheres Muster mit den modernen Flags:

# syntax=docker/dockerfile:1

WORKDIR /app
COPY --link package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY --link src/ ./src/

Versions-Fußnote, damit dieser Abschnitt gut altert: Aktuelle Releases, Stand 2026-09-30, sind Docker Engine 29.8.x, BuildKit 0.33.x, Buildx 0.37.x und Dockerfile-Syntax-Frontend 1.27.x.

Dateien für besseres Caching und Wartbarkeit organisieren

Ein gut organisierter Build-Context macht das Dockerfile leichter wartbar und den Cache leichter nachvollziehbar:

project/
├── src/           # Application source code
├── config/        # Configuration files
├── scripts/       # Build and deployment scripts
├── assets/        # Static assets
└── Dockerfile

Praktische Regeln:

1. Gruppiere verwandte Dateien im selben Verzeichnis
2. Benenne Verzeichnisse nach ihrem Inhalt, nicht danach, wann sie sich ändern
3. Vermeide tiefe Verschachtelung
4. Halte den Context klein, damit der Build schneller startet

Beispiel-Dockerfile mit diesem Layout:

# Copy source code
COPY src/ /app/src/

# Copy configuration files
COPY config/*.json /app/config/

# Copy build scripts
COPY scripts/build.sh /app/scripts/

Wann du gar nicht COPYen solltest: Bind Mounts und Cache Mounts

COPY bäckt Dateien in eine Layer. Das ist das richtige Werkzeug für die Artefakte, die dein Image zur Laufzeit braucht – und das falsche für alles andere. BuildKit-Mounts decken die anderen Fälle ab.

COPY src/ /app/src/

RUN --mount=type=bind,target=/src,rw \
    cp /src/generated/config.json /app/config.json

RUN --mount=type=cache,target=/root/.npm npm ci

Fehlerfälle und Ops-Notizen:

• Bind Mounts persistieren nicht ins finale Image. Leute kopieren Dateien mit einem Bind Mount und wundern sich dann, warum das Verzeichnis zur Laufzeit leer ist.
• Cache Mounts leben im Builder-Storage und wachsen, bis sie geprunt werden. docker builder prune räumt sie auf. Wenn du CI-Builds auf einem VPS laufen lässt, behalte die Platte im Auge.

Deine Layer und den Build-Cache verifizieren

Vertraue nicht dem Dockerfile-Text, vertraue dem, was der Builder produziert hat. Vier Befehle decken fast alles ab:

# Watch context transfer size and per-step CACHED markers
docker build --progress=plain -t myimage .

# Layer-by-layer view with sizes
docker history myimage

# Layer count sanity check (needs jq)
docker image inspect myimage | jq '.RootFS.Layers | length'

# Force-rebuild one stage only, leave the rest cached
docker buildx build --no-cache-filter=deps -t myimage .

Wie „gut” aussieht:

Häufige COPY-Fehler und Fixes

Wenn Builds Müll auf dem Builder hinterlassen, hol dir Festplattenplatz aus /var/lib/docker/overlay2 zurück und räum alte Docker-Images und Build-Cache auf, bevor die Platte es um 3 Uhr morgens für dich tut.

Best Practices für effizientes Dateikopieren

Nutze .dockerignore (und pro-Dockerfile-Ignore-Dateien)

.dockerignore reduziert die Build-Context-Größe, beschleunigt jeden Build und verhindert, dass du versehentlich Secrets und Müll ins Image kopierst.

node_modules/
*.log
.git/
.DS_Store
.env
.env.*

Neuere Docker-Versionen berücksichtigen außerdem pro-Dockerfile-Ignore-Dateien: Eine Datei namens <name>.Dockerfile.dockerignore neben <name>.Dockerfile hat Vorrang vor der Root-.dockerignore. Das ist nützlich in Repos mit getrennten Build-, Lint- und Test-Dockerfiles, die verschiedene Contexts brauchen.

COPY-Schritte nach Änderungshäufigkeit ordnen

Kopiere zuerst Dependency-Manifeste, installiere die Dependencies, dann kopiere den Rest. Code-Änderungen brechen dann nicht deine Dependency-Layer.

WORKDIR /app

# Dependencies (change less often)
COPY package.json package-lock.json ./
RUN npm ci

# App source (changes often)
COPY src/ ./src/

Permission-Falle bei Git-Contexts

Sei vorsichtig mit Wildcards

Wildcards sind praktisch, aber sie können:

• versehentlich zusätzliche Dateien matchen
• deinen Cache mehr brechen, als du erwartest, weil jeder neue Match die Layer invalidiert

Nutze explizite Kopien für cache-kritische Dateien (Dependency-Manifeste) und .dockerignore, um den Context sauber zu halten.

# Good when you control the directory contents (and .dockerignore is set)
COPY config/ /app/config/

# Best for dependency caching (explicit, stable)
COPY package.json package-lock.json /app/

Kurzreferenz

# Multiple specific files into a directory (dest must end with /)
COPY file1.txt file2.txt config.json /app/

# Simple wildcard at context root
COPY *.conf /etc/app/

# syntax=docker/dockerfile:1

# Wildcard set minus exclusions (syntax >= 1.19)
COPY --exclude=*.test.ts --exclude=fixtures/** src/**/*.ts /app/

# syntax=docker/dockerfile:1

# Recursive glob with preserved structure (syntax >= 1.20)
COPY --parents src/**/*.ts /app/

# Multi-stage: keep only what you need, preserving paths
COPY --from=build --parents /out/./app/bin/ /app/

# syntax=docker/dockerfile:1

WORKDIR /app
COPY --link package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY --link src/ ./src/

Die kurze Version

FAQ

COPY file1.txt file2.txt config.json /app/

COPY --exclude=*.test.ts --exclude=fixtures/** src/ /app/src/

Fazit

Zwei Züge decken das meiste ab. Erstens: Ein COPY für Dateien, die sich gemeinsam ändern, bleibt der richtige Default, weil der Cache die ganze Layer invalidiert, wenn sich ein Member ändert. Zweitens: Die Flag-Oberfläche ist größer als früher. --parents, --exclude und --link sind stabil, und # syntax=docker/dockerfile:1 zieht sie herein, egal wie alt das Dockerfile aussieht.

Caching-Disziplin bleibt der eigentliche Performance-Gewinn: kleiner Context, COPY nach Änderungshäufigkeit geordnet, Dependency-Manifeste vor dem Source. Layer-Golf ist Rauschen.

Wenn der Rebuild fertig ist und du das neue Image ausrollst, siehe wie man einen Container mit Docker Compose aktualisiert.

Wenn du auf einem VPS oder einem self-hosted CI-Runner baust und deployst, reicht eine kleine Hetzner-Cloud-Instanz für Docker-Image-Builds dieser Größe aus.