Yes, we're now running our Black Friday Sale. All Access and Pro are 33% off until 2nd December, 2025:
Difference Between COPY and ADD in a Dockerfile
Last updated: November 6, 2023
Modern software architecture is often broken. Slow delivery leads to missed opportunities, innovation is stalled due to architectural complexities, and engineering resources are exceedingly expensive.
Orkes is the leading workflow orchestration platform built to enable teams to transform the way they develop, connect, and deploy applications, microservices, AI agents, and more.
With Orkes Conductor managed through Orkes Cloud, developers can focus on building mission critical applications without worrying about infrastructure maintenance to meet goals and, simply put, taking new products live faster and reducing total cost of ownership.
Try a 14-Day Free Trial of Orkes Conductor today.
1. Introduction
When creating Dockerfiles, it’s often necessary to transfer files from the host system into the Docker image. These could be property files, native libraries, or other static content that our applications will require at runtime.
The Dockerfile specification provides two ways to copy files from the source system into an image: the COPY and ADD directives.
In this article, we’ll look at the differences between them and when it makes sense to use each one.
2. Difference Between COPY and ADD
At first glance, the COPY and ADD directives look the same. They have the same syntax:
COPY <source> <destination>
ADD <source> <destination>And both copy files from the host system to the Docker image.
So what’s the difference? In short, the ADD directive is more capable than COPY.
While functionally similar, the ADD directive is more powerful in two ways:
- It can handle remote URLs
- It can auto-extract tar files
Let’s look at these more closely.
First, the ADD directive can accept a remote URL for its source argument. The COPY directive, on the other hand, can only accept local files.
Note that using ADD to fetch remote files and copying is not typically ideal. This is because the file will increase the overall Docker image size. Instead, we should use curl or wget to fetch remote files and remove them when no longer needed.
Second, the ADD directive will automatically expand tar files into the image file system. While this can reduce the number of Dockerfile steps required to build an image, it may not be desired in all cases.
Note that the auto-expansion only occurs when the source file is local to the host system.
3. When to Use ADD or COPY
According to the Dockerfile best practices guide, we should always prefer COPY over ADD unless we specifically need one of the two additional features of ADD.
As noted above, using ADD to copy remote files into a Docker image creates an extra layer and increases the file size. If we use wget or curl instead, we can remove the files afterward, and they don’t remain a permanent part of the Docker image.
Additionally, since the ADD command automatically expands tar files and certain compressed formats, it can lead to unexpected files being written to the file system in our images.
4. Conclusion
In this quick tutorial, we’ve seen the two primary ways to copy files into a Docker image: ADD and COPY. While functionally similar, the COPY directive is preferred for most cases. This is because the ADD directive provides additional functionality that should be used with caution and only when needed.