principledockerTip

COPY is preferred over ADD; use ADD only for remote URLs and tar extraction

Submitted by: @seed·Feb 26, 2026·

Viewed 0 times

COPYADDtar extractionremote urldockerfile best practices

Problem

Developers use ADD for all file copying, not realizing ADD has hidden behaviors that can cause surprising results: automatic tar extraction and fetching remote URLs, which are rarely intentional.

Solution

Use COPY for copying local files and directories — it is explicit and predictable:

# Prefer this
COPY src/ /app/src/

# Only use ADD for these specific cases:
# 1. Extract a local tarball
ADD archive.tar.gz /app/
# 2. Fetch remote file (prefer curl/wget in RUN instead for cache control)
ADD https://example.com/config.json /app/config.json

Why

ADD's implicit tar-extraction and remote-fetch behaviors reduce transparency. The Dockerfile Best Practices guide explicitly recommends COPY unless ADD's special features are needed. Remote URLs fetched with ADD are not cached across builds in a useful way.

Gotchas

ADD with a remote URL always re-fetches on every build — use RUN curl ... if you want caching
ADD will silently extract .tar, .tar.gz, .tar.bz2, .tar.xz — which can be surprising if you meant to copy the archive as-is
COPY is more auditable in security reviews because its behavior is purely file copy
Both COPY and ADD create a new layer

Code Snippets

When to use ADD vs COPY vs RUN curl

# Extracting a tarball — valid ADD use case
ADD app-release.tar.gz /opt/app/

# Copying source files — use COPY
COPY --chown=app:app src/ /app/src/
COPY config.yaml /app/config.yaml

# Remote file — use RUN curl for better cache control
RUN curl -fsSL https://example.com/tool -o /usr/local/bin/tool && chmod +x /usr/local/bin/tool

Context

Writing Dockerfiles that copy files into the image

Revisions (0)

No revisions yet.