4.2.4 ADD
A focused guide to ADD, connecting core concepts with practical Docker and container operations.
ADD is a Dockerfile instruction similar to COPY but with two additional capabilities: automatically extracting recognized compressed archive formats, and fetching files directly from a remote URL — capabilities that add convenience but also introduce behavior that is less immediately obvious from reading the instruction alone.
Basic File Copying, Same as COPY
For simply copying a file or directory from the build context, ADD behaves identically to COPY.
ADD app.py /app/app.py
COPY app.py /app/app.py
Both produce the same result in this case, since neither archive extraction nor a remote URL is involved.
Automatic Archive Extraction
When the source is a recognized compressed archive format, ADD automatically extracts its contents into the destination, rather than copying the archive file itself.
ADD app.tar.gz /app/
This extracts the archive's contents directly into /app/, which is meaningfully different behavior than COPY would produce with the same instruction.
Fetching From a Remote URL
ADD can also retrieve a file directly from a URL during the build, downloading it as part of the build process rather than requiring it to already exist in the build context.
ADD https://example.com/data.json /app/data.json
Why This Additional Behavior Is a Tradeoff
Because ADD's extra capabilities are not obvious just from glancing at an instruction, a Dockerfile using ADD for simple file copying can be misread, with a reader assuming COPY-like behavior when something more complex (extraction, remote fetching) is actually happening.
ADD config.tar.gz /app/config/
A reader unfamiliar with ADD's extraction behavior might be surprised that this results in extracted files rather than the archive itself being present in the destination.
Why Understanding ADD Matters
Knowing exactly what additional behavior ADD introduces beyond plain copying is essential both for using it correctly when its extra capabilities are genuinely needed, and for recognizing why many style guides recommend reserving it specifically for those cases rather than using it as a default alternative to COPY.