What is the difference between COPY and ADD commands in Dockerfile?
Both `COPY` and `ADD` are Dockerfile instructions used to transfer files from a source location (usually the Docker build context) into a Docker image. While they share a fundamental purpose, `ADD` offers additional functionalities that differentiate it from `COPY`.
COPY Command
The COPY instruction copies new files or directories from <src> and adds them to the filesystem of the image at the path <dest>. It is a straightforward and explicit command designed solely for copying local files and directories from the build context into the image.
It requires the source to be relative to the build context. If the source is a directory, its entire content, including filesystem metadata, is copied. If it's a file, it's copied directly. COPY is generally preferred for its transparency and predictability.
ADD Command
The ADD instruction also copies new files, directories, or remote file URLs from <src> and adds them to the filesystem of the image at the path <dest>. While it performs the basic copying function like COPY, ADD has two unique capabilities:
- Tar Extraction: If the <src> is a tar archive (compressed or uncompressed like
.tar,.tar.gz,.tgz,.bzip2,.xz),ADDwill automatically decompress and extract its contents into the destination directory inside the image. - Remote URL Support: If the <src> is a URL,
ADDwill download the file from that URL and place it at the <dest> in the image. This feature is often discouraged due to caching issues and security concerns, withcurlorwgettypically preferred in aRUNinstruction.
Key Differences and Use Cases
| Feature | COPY | ADD |
|---|---|---|
| Local File/Directory Copying | Yes | Yes |
| URL Support (Download) | No | Yes (discouraged) |
| Automatic Tar Extraction | No | Yes (if source is a tarball) |
| Transparency/Predictability | High | Lower (due to 'magic' features) |
| Best Practice | Preferred for most local file transfers | Use only when tar extraction is explicitly needed |
When to use COPY
Always prefer COPY when you are simply moving local files or directories from your build context into the Docker image. It's more explicit, easier to understand, and prevents unintended behavior like tar extraction or accidental URL downloads. It's also less prone to unexpected caching issues compared to ADD's URL feature.
COPY . /app
COPY package.json /app/package.jsonWhen to use ADD
Use ADD specifically when you need its unique capabilities: automatic tarball extraction into the image. For downloading files from URLs, it's generally recommended to use RUN combined with curl or wget for better control over caching, authentication, and error handling.
ADD source.tar.gz /app/