Docker COPY vs ADD: What’s the difference?

If you build container images using Dockerfiles, you’ve most likely encountered the Docker instructions ADD and COPY. ADD and COPY both provide a similar function, in that they both allow you to get folders and files into your images at build time. So which one should you use?

In this post, I’ll go over some of the nuances between COPY vs ADD and help you determine when to use which.

Your keys to a better career

Get started with ACG today to transform your career with courses and real hands-on labs in AWS, Microsoft Azure, Google Cloud, and beyond.

First, let’s talk about the ADD instruction. The ADD instruction has always been part of Docker. ADD uses two arguments: source and destination. 

• The source argument will work with all types of files and is relative to the build context. 

• The destination argument can be an absolute path or a relative path to WORKDIR.

ADD also has some other “magic” that it can perform. ADD also supports downloading files from remote URLs. In addition to remote file support, ADD can also automatically extract various types of archives into the image. If the source you provide is an archive compressed with tar, gzip, bzip2, or xz, ADD will automatically extract the archive into the provided destination. It should be noted it determines the type of archive by the contents, not simply by using the file extension.

Now let’s take a look at the COPY instruction. COPY was added as an instruction with the release of Docker version 1.0. Like ADD, COPY also lets you get files and folders into your image. 

It has two arguments as well: source and destination.

However, the COPY instruction is more straightforward and doesn’t have some of the extra features of ADD. COPY will not work with a URL, and it also copies archives as-is rather than trying to extract them.

Why two different instructions that do the same thing?

A long time back, an issue was raised pointing out that the ADD instruction didn’t always work as expected. Maybe you had a tar archive file you wanted to copy but not extract. ADD would try to extract it. Also, you may have a tar archive compressed in an unrecognized format. You may try to use ADD to extract it, but because it isn’t recognized, ADD instead copies it as a file. 

Overall, the greater opinion was that ADD was trying to do too much. So the new instruction COPY was added into Docker. ADD is kept as an instruction as to not break backwards compatibility — plus some developers like the additional features provided by ADD.

So when should you use ADD and when should you use COPY? According to the Docker best practices guide you should generally be using COPY — but your mileage may vary. 

You may want to use ADD for the remote URL feature or uncompressing of archives. An unintentional ADD instead of COPY instruction can mean the difference between a functional image and a “broken” one. For example you need to have a tar archive in your image as an archive. If you accidentally use ADD you will end up with the contents of the archive and not the actual image. 

With regards to the remote URL feature of ADD, you might be better off using a RUN instruction and providing the command curl or wget to download the file and then follow that command with a tar or unzip (if it’s an archive file), or other commands you may need to run for your image. This method results in fewer instructions and fewer instructions creates smaller images.

For more information on ADD and COPY, make sure to check out the official Docker builder reference.

Looking to learn more about containers? Check out our new Red Hat Certified Specialist in Containers and Kubernetes Exam (EX180) course. It's designed to help you obtain the knowledge and skills required to pass the EX180 exam and will give you hands-on experience creating, managing, and deploying containerized solutions using Red Hat OpenShift.

Keep up with all things tech skills by following Twitter, Facebook, subscribing to A Cloud Guru on YouTube, or joining the conversation in our Discord Community. And check out this month's rotating roster of free tech training!