4.2.4.3 ADD COPY Contrast
A focused guide to ADD COPY Contrast, connecting core concepts with practical Docker and container operations.
The ADD-COPY contrast summarizes the practical differences between Docker's two file-copying instructions, clarifying why most style guides recommend defaulting to COPY and reserving ADD specifically for the cases that genuinely need its additional capabilities.
Feature Comparison
COPY does exactly one thing: copy files or directories from the build context into the image. ADD does that too, but additionally extracts recognized compressed archives automatically and can fetch files directly from a remote URL.
COPY app.tar.gz /app/
ADD app.tar.gz /app/
The first results in the archive file itself being present inside the image; the second results in its extracted contents being present instead — a meaningful behavioral difference for what otherwise looks like a nearly identical instruction.
Predictability as the Deciding Factor
Because COPY's behavior is simple and consistent regardless of what kind of file is involved, a Dockerfile using COPY exclusively for ordinary file copying is easier to read correctly without needing to recall any special-case behavior.
COPY . /app
A reader can be confident this instruction copies the build context's contents exactly as they are, with no hidden extraction or network behavior to account for.
When ADD's Extra Capabilities Are Actually Needed
ADD remains the right choice specifically when archive extraction is genuinely desired as part of the copy operation, since achieving the same result with COPY would require an additional, explicit extraction step.
ADD release.tar.gz /opt/app/
A Common Convention
Many teams adopt a simple rule: use COPY by default for everything, and reach for ADD only in the specific, deliberate case of wanting automatic archive extraction, treating its remote URL fetching capability as something to avoid entirely for reproducibility reasons.
COPY src/ ./src/
ADD vendor-release.tar.gz /opt/vendor/
Why This Contrast Matters
Understanding the precise difference between these two instructions, rather than treating them as interchangeable, prevents both confusing, unintended extraction behavior and the loss of build reproducibility that can come from ADD's remote URL fetching capability.