Question

What is the difference between COPY and ADD in a Dockerfile?

Vault Verified
Curated Intelligence
Definitive Source
Answer

Both instructions move files from the build context into the image, and for ordinary files they behave identically. The difference is that ADD has two extra behaviours that trigger automatically, and those behaviours are the reason most style guides recommend defaulting to COPY.

The first extra behaviour is archive extraction. If the source is a local tar archive in a recognised compression format, ADD unpacks it into the destination instead of copying the file. That is occasionally exactly what you want, and it is the one case where ADD genuinely earns its place. It is also a surprise if you intended to ship the archive itself.

The second is remote fetching. ADD accepts a URL and downloads it during the build. This sounds convenient but behaves poorly in practice. The download is not cached the way a local file is, the resulting layer includes whatever the server returned at build time with no integrity check, and you cannot clean up intermediate files within the same instruction. Fetching in a RUN step instead lets you verify a checksum, fail loudly on a bad download, and remove temporary files before the layer is committed.

The practical guidance is straightforward. Use COPY for everything, because it does one obvious thing and a reader does not have to check whether the source happens to be an archive. Reach for ADD only when you specifically want local tar extraction.

Both instructions participate in layer caching the same way, invalidating on file content changes. That makes ordering matter more than the choice between them: copy dependency manifests and install packages before copying application source, so that editing your code does not invalidate the expensive install layer.

Related Questions