📄 COPY is Simple. ADD has Extra Features.
Both copy files into image. COPY is simple file copy. ADD can download URLs and extract archives. Use COPY unless you need ADD features.
📦 COPY (Simple)
COPY app.js /app/ COPY src/ /app/src/ COPY --chown=user:group file /app/
📦 ADD (Extra Features)
ADD https://example.com/file.tar.gz /app/ ADD archive.tar.gz /app/ # Auto-extract ADD --chown=user:group file /app/
🎯 Best Practices
# ✅ Use COPY for local files COPY package.json package-lock.json ./ COPY src/ ./src # ✅ Use ADD for remote files (rare) ADD https://example.com/cert.pem /app/cert.pem # ✅ Use ADD for archive extraction (rare) ADD archive.tar.gz /app/ # Automatically extracts # ❌ Don't use ADD for local files (use COPY) ADD app.js /app/ # Works but COPY is preferred # ❌ Don't use COPY for remote files (use ADD) COPY https://example.com/file /app/ # Doesn't work! # Why COPY is preferred: # - Clear intent (only copies files) # - Build cache works better # - No unexpected extraction
💡 Summary
- COPY: Use for local files (preferred, clear intent)
- ADD: Use for remote URLs or archive extraction
- Both support –chown to set ownership
- ADD auto-extracts tar.gz, tar, zip (avoid unexpected behavior)
- Docker best practice: prefer COPY unless you need ADD features
“Used ADD everywhere. ADD extracted a tar.gz unexpectedly, broke my build. Switched to COPY for local files, ADD only for downloads. Now builds are predictable.”