Why should COPY be used instead of ADD in Dockerfiles?

Why COPY is the safer default in Dockerfiles

Dockerfile instructions should be boring when they can be. COPY is explicit: it moves files from the build context into the image and nothing else. That makes the build easier to review, easier to reproduce, and easier to reason about in code review, because the instruction does not introduce extra behaviour that changes what enters the image.

That predictability matters for supply chain hygiene. A Docker image is part of the software artifact your teams will run, scan, sign, and promote, so the build step should avoid hidden side effects. Using COPY keeps the input set narrow and visible, which supports container image integrity and reduces the chance of accidentally pulling in content you did not intend to ship. For teams standardising image hardening, the Container Image Security Guide is a useful starting point for the broader controls around base images, provenance, and image trust.

ADD is not inherently bad, but it is broader than many teams need. In addition to copying files, it can unpack local archives and fetch remote content, which means the same line can hide multiple actions and multiple trust assumptions. That extra power is why ADD is easy to misuse in ways that make builds less predictable and harder to review.

What ADD changes that COPY does not

The practical difference is not syntax, it is semantics. COPY is a straightforward file transfer from the build context. ADD may also interpret the source as an archive and extract it, or treat a URL as a fetch target depending on usage and builder behaviour. Those extra behaviours can be useful, but they also expand the number of things a maintainer must verify before trusting the Dockerfile.

That matters most when the source is not fully under your control. If a Dockerfile can silently fetch remote content, you have introduced an availability dependency, a trust dependency, and a review problem at the same time. If it can auto-extract archives, you also need to think about what paths will be created and whether the extracted tree is exactly what you intended. The safer habit is to use COPY for ordinary file inclusion and reserve ADD for the narrow cases where archive extraction or remote-source handling is truly part of the build design.

When the build needs to move content into the image without any special behaviour, COPY keeps the security model simple: the image contains only what the repository and build context already provided. When the build needs an archive unpacked, that should be a deliberate choice with an explicit source review rather than an implicit convenience.

When to use ADD, and what to check first

Use ADD only when its extra behaviour is the point of the instruction, not as a shortcut. If you are unpacking a local archive or intentionally bringing in content from a remote source, confirm that the source is controlled, that the extraction result is expected, and that the final image contents are still deterministic enough for your release process.

For higher-assurance container workflows, it helps to treat Dockerfile instructions as part of the build contract. The moment an instruction reaches outside the repository, expands content automatically, or changes the artifact in a way that is not obvious from a quick read, it deserves the same scrutiny you would give any other supply-chain dependency. Teams that want a deeper baseline for those concerns should align build practices with the CSA Cloud Controls Matrix where cloud supply-chain, image, and governance controls intersect, and with the NIST SP 800-53 Rev 5 Security and Privacy Controls for configuration management and integrity-oriented build controls.

Risk and Threat Considerations

Using ADD where COPY would do creates avoidable build ambiguity. That ambiguity can conceal unexpected content, make reviews miss the real artifact change, and widen the attack surface if the build fetches or unpacks something you did not mean to trust. In container pipelines, that is not just a style issue, it is a control issue.

Failure mechanism: An image build accepts extra behaviour from ADD, such as archive extraction or remote retrieval, and the resulting filesystem contents diverge from what the reviewer expected from the file list alone.

Impact: The image can become harder to reproduce, easier to misuse, and more difficult to inspect for hidden or undesired content, especially when the source material is external or loosely controlled.

Practitioner Guidance

What to verify: Check whether the build step really needs extraction or remote retrieval. If it does not, replace ADD with COPY and keep the image assembly path as explicit as possible. If it does, document the reason in the Dockerfile review so future maintainers know the exception is intentional.

Common mistake: Treating ADD as a harmless convenience because the image still builds. The issue is not whether the build succeeds, it is whether the instruction makes the artifact harder to audit, harder to reproduce, or easier to change unintentionally.

Practitioner takeaway: Prefer COPY by default because the safest Dockerfiles are the ones with the fewest hidden behaviours; use ADD only when its special handling is genuinely required and has been consciously reviewed.

Related resources from NHI Mgmt Group

• What breaks in SaaS security when a widely used component like Log4j is embedded in integrations and add-ons instead of just the core platform?
• When should organisations add runtime controls for AI agents instead of relying on monitoring?
• What breaks when network controls are used instead of request-level policy for machine access?
• What breaks when observability is used instead of access control for AI agents?