COPY vs ADD im Dockerfile - wann man was verwenden sollte

COPY und ADD kopieren beide Dateien in das Image — aber sie sind nicht austauschbar. Die Wahl zwischen den beiden ist eine Frage der Transparenz.

COPY: das klare Werkzeug

COPY tut genau eine Sache: Dateien oder Verzeichnisse vom Build-Kontext ins Image kopieren. Nicht mehr, nicht weniger.

COPY index.html /var/www/html/
COPY src/ /app/src/
COPY package.json package-lock.json /app/

Was man sieht, ist was passiert. Das macht COPY zur richtigen Wahl für den Großteil aller Anwendungsfälle.

ADD: der Schweizer Taschenmesser

ADD kann alles was COPY kann — und noch zwei Dinge mehr:

1. URLs als Quelle:

ADD https://example.com/config.tar.gz /tmp/

2. Automatisches Entpacken von tar-Archiven:

ADD archive.tar.gz /app/
# Inhalt von archive.tar.gz wird nach /app/ entpackt

Das klingt praktisch, ist aber oft eine Falle. Das automatische Entpacken passiert still — wer nicht weiß, was ADD macht, wundert sich über Dateien, die "magisch" im Image auftauchen.

Best Practice: fast immer COPY

Die offizielle Docker-Dokumentation empfiehlt COPY als Standard. ADD nur dann, wenn man die Extra-Funktionen bewusst und explizit braucht.

• Gründe für COPY:
• Vorhersagbares Verhalten — kein stilles Entpacken
• Klarer zu lesen für andere Entwickler
• Kein unerwartetes Netzwerk-Request beim Build

Für tar-Archive, die entpackt werden sollen, ist ADD legitim:

# Sinnvoll: Source-Archiv direkt entpacken
ADD src-v1.2.3.tar.gz /app/

Für URL-Downloads ist ADD weniger empfehlenswert, weil der Layer gecacht wird und spätere Änderungen an der URL nicht erkannt werden. Besser:

# Transparenter und cache-sicherer
RUN curl -fsSL https://example.com/tool.tar.gz | tar -xz -C /opt/tool

Zusammenfassung

| | COPY | ADD |
|---|---|---|
| Dateien kopieren | ja | ja |
| Verzeichnisse kopieren | ja | ja |
| URLs als Quelle | nein | ja |
| tar automatisch entpacken | nein | ja |
| Empfohlen als Standard | ja | nein |

Faustregel: Mit COPY anfangen. Nur zu ADD wechseln, wenn man das Entpacken von Archiven explizit will — und auch dann weiß man, warum.