4.2.4.4 ADD Misuse Cases

ADD misuse cases are the common situations where ADD is used out of habit or unfamiliarity rather than genuine need, often producing unexpected behavior or undermining build reproducibility in ways that would not occur if COPY had been used instead.

Misuse: Copying an Archive Without Wanting Extraction

A frequent mistake is using ADD to bring an archive file into an image when the actual intent was simply to copy the archive itself, not to extract it.

ADD backup.tar.gz /backups/

If the goal was to store this archive file as-is for later retrieval, this instruction does not achieve that, since ADD extracts it automatically into the destination instead.

Misuse: Fetching From a URL for Convenience

Using ADD's remote URL fetching simply because it is convenient, without considering that the fetched content could change over time, undermines the reproducibility of the build.

ADD https://example.com/current-config.json /app/config.json

If the content at this URL changes after the image is first built, rebuilding it later produces a different result, despite the Dockerfile text remaining identical.

Misuse: Using ADD as a Default Habit

Some Dockerfiles use ADD for every file-copying operation purely out of habit, even when none of its additional capabilities are actually relevant, which makes the Dockerfile harder to read confidently, since a reader cannot assume simple copying behavior without checking each source file's type.

ADD app.py /app/app.py
ADD config.yaml /app/config.yaml

COPY app.py /app/app.py
COPY config.yaml /app/config.yaml

Both produce the same result here, but the second signals unambiguously, without any need to check file types, that no special extraction or fetching behavior is involved.

Identifying Existing Misuse

Reviewing an existing Dockerfile for ADD instructions and confirming whether each one genuinely needs ADD's extra capabilities is a useful exercise for catching unintentional misuse.

grep -n "^ADD" Dockerfile

Why Avoiding These Misuse Cases Matters

Recognizing these common misuse patterns helps maintain both the predictability of a Dockerfile's behavior and the reproducibility of its builds, two qualities that are easy to lose by reaching for ADD without a specific, deliberate reason.