Before comparing the two instructions, it helps to understand the basic problem both of them exist to solve: getting files from outside a container image into the filesystem that image will contain.

Why a Dockerfile Needs to Move Files At All

A Docker image starts, in most cases, from a base image containing an operating system and perhaps a language runtime, but no application code. Somewhere in the process of building a custom image, the actual application source code, configuration files, or static assets have to make their way from the machine performing the build into the image’s own filesystem layers. This is a fundamentally different problem than running a command inside the image, because the files being copied usually live outside the container entirely, sitting on the disk of whichever machine is running docker build.

What COPY Does

The COPY instruction does exactly one job: it copies files or directories from the build context — the folder you pointed docker build at — into a specified location inside the image being built. It is a direct, literal file copy operation, comparable to dragging a file from one folder to another on your own computer. It does not fetch anything from the internet, and it does not automatically unpack compressed archives.

What ADD Does

The ADD instruction can do everything COPY does, plus two additional, automatic behaviors: if the source is a recognized compressed archive format (such as a tar file, optionally gzip or bzip2 compressed) located in the build context, ADD automatically extracts its contents into the destination directory instead of copying the archive file itself; and if the source is a URL rather than a local file, ADD will download that remote file and place it in the image.

Why This Distinction Matters From Day One

Because ADD’s extra behaviors are triggered automatically based on what the source looks like, rather than through an explicit flag the Dockerfile author chooses, its behavior can be harder to predict at a glance. A teammate reading a Dockerfile with a COPY instruction knows immediately and unambiguously what will happen. A teammate reading an ADD instruction has to first check whether the source is a plain file, an archive, or a URL, because each one leads to meaningfully different behavior in the final image.

Both instructions sit inside Docker’s broader build architecture, particularly the concept of the build context and the layered filesystem that every image is made of.

The Build Context

When a Dockerfile is built, Docker first gathers every file in a specified directory — commonly the current folder — into something called the build context, and sends that entire context to the build engine before a single instruction runs. Both COPY and ADD can only reference files that exist inside this build context; neither instruction can reach outside of it to grab an arbitrary file from elsewhere on the host machine’s filesystem, which is a deliberate security boundary preventing a Dockerfile from accidentally, or maliciously, pulling in unrelated files it was never meant to see.

flowchart LR
    A["Host Machine Folder
(the build context)"] -->|docker build .| B["Build Context
Sent to Build Engine"]
    B --> C{"Dockerfile Instruction"}
    C -->|COPY src dest| D["Direct file copy
into new image layer"]
    C -->|"ADD src.tar.gz dest"| E["Automatic extraction
into new image layer"]
    C -->|"ADD https://... dest"| F["Remote download
into new image layer"]
    D --> G["Final Image Filesystem"]
    E --> G
    F --> G
        

Layers and Image Size

Every COPY or ADD instruction creates a new, immutable layer in the resulting image. Understanding this matters directly for image size and build speed: if a large file is copied in an early layer and later removed in a subsequent instruction, the bytes from that file are still physically present in the earlier layer and still count toward the final image’s total size, because layers are additive and earlier ones are never silently rewritten by later ones.

Ownership and Permissions

Both instructions support an option to set the ownership (user and group) of the copied files as they land inside the image, which matters a great deal for images designed to run as a non-root user — a very common security best practice. Without explicitly setting ownership, copied files typically land owned by the root user by default, which can cause a permission error later if the container’s main process is deliberately configured to run as a different, non-root user.

Understanding exactly what happens, step by step, during each type of copy operation clarifies why the two instructions behave so differently in practice.

How COPY Processes a Request

When the build engine reaches a COPY instruction, it looks up the specified source path or paths inside the already-collected build context, verifies they exist, and writes their exact bytes into the destination path inside a new image layer. There is no interpretation of file type, no decision-making about whether something looks like an archive, and no network activity of any kind. What goes in is exactly what comes out, one-to-one.

How ADD Processes a Local Archive

When ADD encounters a source file in the build context that matches a recognized compressed archive format, it does not simply copy that archive file into the destination as a single compressed file. Instead, it automatically unpacks the archive’s contents directly into the destination directory, as though someone had manually extracted it and then copied each resulting file over individually. This automatic extraction only applies to local files in the build context — if the exact same archive were instead placed at a remote URL, ADD’s URL-handling path does not perform this same automatic extraction, which is a subtle but important asymmetry to remember.

How ADD Processes a Remote URL

When the source given to ADD is a URL rather than a local path, the build engine performs an HTTP request during the image build itself, downloads the resulting file, and places it at the specified destination inside the new layer. This means the network has to be reachable at build time for this step to succeed, and the exact bytes downloaded depend entirely on what that remote URL happens to serve back at the moment the build runs — which may not be the same content every time, especially if the URL points at something that changes over time.

sequenceDiagram
    participant Ctx as Build Context
    participant Build as Build Engine
    participant Net as Remote Server
    participant Img as New Image Layer
    Build->>Ctx: Read local source for COPY
    Ctx-->>Build: Return raw file bytes
    Build->>Img: Write bytes unchanged
    Note over Build,Img: COPY: no branching logic
    Build->>Ctx: Read local source for ADD
    alt Source is a recognized archive
        Ctx-->>Build: Return archive bytes
        Build->>Build: Extract archive contents
        Build->>Img: Write extracted files
    else Source is a URL
        Build->>Net: HTTP GET request
        Net-->>Build: Return remote file bytes
        Build->>Img: Write downloaded file as-is
    end
        

Why Reproducibility Suffers With Remote ADD

Because a URL-based ADD performs a live network request at build time, the exact same Dockerfile can theoretically produce a different image on two separate build runs if the content at that URL changes in between — something that would never happen with a COPY instruction referencing a fixed, version-controlled local file, since the build context itself does not silently change between runs unless the developer deliberately changes it.

Tracing a file’s journey from a developer’s own repository all the way into a running container makes clear exactly where COPY and ADD sit in the broader build-and-deploy lifecycle.

Build Cache and Instruction Ordering

Docker’s build cache checks whether the content being copied has changed since the previous build; if it hasn’t, Docker can reuse the previously built layer instead of repeating the copy operation, which significantly speeds up repeated builds. This is precisely why experienced Dockerfile authors deliberately order their COPY instructions carefully — copying files that rarely change (such as a dependency manifest) before files that change constantly (such as application source code), so that a small source code edit doesn’t invalidate and force a rebuild of an expensive dependency installation step that didn’t actually need to change.

Where the URL-Fetching Behavior Breaks This Lifecycle

Because a URL-based ADD performs a live network call, its build cache behavior is comparatively less predictable than a local COPY — the cache generally keys off the instruction’s declared source, not off freshly re-checking the remote content’s current state on every single build, which means a changed remote file might not automatically trigger a fresh download unless the build cache is deliberately invalidated. This is one more reason experienced teams generally prefer downloading remote files in a separate, explicit, controlled step, rather than relying on ADD’s built-in URL behavior.

Neither instruction is universally “better” — each represents a different trade-off between simplicity and convenience.

Why Official Guidance Leans Toward COPY

Docker’s own documentation explicitly recommends COPY for the majority of cases specifically because of its predictability: a Dockerfile is a piece of infrastructure that is often read, reviewed, and modified by people other than its original author, sometimes years later. An instruction whose behavior can be fully understood without needing to check the nature of its source file is significantly easier to maintain safely over that long lifespan than one requiring extra context to interpret correctly.

Where ADD’s Extra Power Genuinely Helps

The one case where ADD’s automatic archive extraction is broadly considered a legitimate, even preferred, choice is unpacking a local tarball of application files directly into an image in a single instruction, avoiding a separate manual extraction step elsewhere in the build. Outside of this specific case, and outside of a handful of ADD’s own documented, narrow local-archive scenarios, most style guides and linters actively recommend against reaching for ADD’s remote URL behavior in production Dockerfiles.

The extra automatic behaviors that make ADD more powerful than COPY are precisely the same behaviors that introduce meaningful security considerations.

The Risk of Fetching Remote Content During a Build

Using ADD with a remote URL means the build process itself reaches out to a server outside of your control, at build time, and trusts whatever content that server returns. If that URL is ever compromised, redirected, or simply serves different content than expected, the resulting image can silently contain unexpected, potentially malicious content, without the Dockerfile itself ever visibly changing. This is a meaningfully larger trust surface than a COPY instruction referencing a file that already lives, reviewed and version-controlled, inside the same repository as the Dockerfile.

Extraction Behavior and Archive Contents

Automatic extraction of an archive means every file packed inside that archive lands inside the image, whether or not the Dockerfile author fully audited every single file the archive contains. An archive built by an unfamiliar third-party tool or process could, in principle, include far more files than expected, and ADD’s automatic unpacking behavior means those extra files land inside the image without any additional visible step in the Dockerfile drawing attention to them.

Why Explicit, Separate Download Steps Are Often Preferred

Rather than relying on ADD’s built-in URL fetching, many security-conscious teams prefer to perform any necessary downloads as an explicit, separate, auditable step — one that can include verifying a cryptographic checksum of the downloaded file against a known-good value before it is trusted and copied into the image. This extra verification step is something ADD’s built-in URL behavior does not perform automatically, meaning a Dockerfile relying on it alone has no built-in protection against a tampered or unexpectedly different remote file.

While COPY and ADD are build-time instructions with no runtime footprint of their own, their effects on image size, build reliability, and reproducibility are all worth actively tracking.

Tracking Image Size Contribution

Because every COPY or ADD instruction adds a new layer, teams that care about lean images regularly inspect which layers contribute the most to an image’s total size, often discovering that an early, forgotten COPY of an unnecessarily large file (such as an entire local dependency cache folder that should have been excluded) is quietly bloating every derived image built from that Dockerfile ever since.

A Real Pattern: Flagging Remote ADD Usage in CI

Some organizations configure a linting step in their continuous integration pipeline that specifically scans every Dockerfile for ADD instructions pointing at a URL, flagging them for manual review rather than allowing them to merge automatically. This turns a subtle, easy-to-miss pattern into a visible, actively monitored signal the team can consciously accept or reject on a case-by-case basis.

A handful of clear, well-established patterns have emerged from years of real-world Dockerfile authorship around exactly when to reach for COPY versus ADD.

Pattern: Default to COPY, Always

The single most widely agreed-upon pattern across the Docker community is to default to COPY for essentially every file transfer, and to reach for ADD only when one of its specific extra behaviors is genuinely needed and deliberately chosen, never out of habit or because an old tutorial happened to use it.

Pattern: Multi-Stage Builds Combined With COPY

In a multi-stage build, a special form of COPY can pull files not from the local build context, but directly from an earlier build stage — for example, copying only a compiled binary out of a large build-tooling stage into a small, final runtime stage. This pattern keeps the final image lean while still allowing the build process itself to use whatever large, heavy tools it needs in an earlier, discarded stage.

Pattern: Reserving ADD Strictly for Local Archive Extraction

When a project genuinely needs to unpack a local tarball as part of its build, using ADD for that single, specific purpose remains a reasonable, well-understood pattern — the key discipline is using it only for that purpose, and continuing to use COPY for every other file in the same Dockerfile, rather than switching entirely to ADD everywhere out of convenience.

Anti-pattern: Fetching Application Dependencies With Remote ADD

Some Dockerfiles use ADD with a URL to fetch an entire application dependency, such as a specific tool binary, directly during the build. This bypasses whatever dependency management and version-locking practices a project otherwise follows elsewhere, and ties every future build’s success to that one remote URL remaining available and unchanged indefinitely.

Pattern: Explicit .dockerignore as a Companion to COPY

Because a broad COPY instruction naturally pulls in everything present in its source directory, mature projects pair it with an ignore file that explicitly lists paths to exclude from the build context entirely — things like local dependency caches, editor configuration folders, and version control metadata. This means a simple, broad COPY instruction stays safe and lean, because the unwanted files never even make it into the build context in the first place, rather than relying on the Dockerfile author to remember every exclusion at the moment they write each individual COPY line.