Raunak Jain

Posted on Feb 22

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

Docker is a tool that makes it easier to run applications in containers. In every project, a Dockerfile is used to create a Docker image. A Dockerfile is a plain text file with a list of instructions. Two important instructions are COPY and ADD. At first glance, they seem very similar. But they have differences that can affect how your image is built.

In this article, I will explain both commands in simple words. I will also show examples and best practices. This guide is for beginners who are learning Docker. I try to use simple sentences and a friendly tone. You can learn more about Dockerfiles in this guide on creating a Dockerfile which explains the basics.

What is a Dockerfile?

A Dockerfile is like a recipe. It tells Docker how to build your image step by step. Each instruction creates a new layer in your image. The final image contains all the layers from the instructions. The Dockerfile can include commands to copy files, install programs, and set up the environment. Understanding the Dockerfile is very important. If you want to know more about how images are built, check out how to build a Docker image from a Dockerfile for clear steps.

The COPY Command

The COPY command is used to copy files or directories from your host computer (or build context) to the image. It is very simple and does exactly what it says. No extra work is done by COPY.

How COPY Works

When you write a Dockerfile, you use COPY like this:

COPY ./source_folder /destination_folder

This instruction tells Docker to copy the contents of ./source_folder on your computer into /destination_folder in the image. COPY does not unpack files or do any processing. It just copies the data.

Advantages of Using COPY

Simplicity: COPY only copies files. It does not add extra functionality. This makes it predictable and easy to understand.
Transparency: With COPY, you know exactly what is being copied.
Layer Management: Since every command creates a new image layer, using COPY helps keep layers clear. For more on image layers, see understanding Docker image layers.

The ADD Command

The ADD command looks like COPY but has extra features. In addition to copying files, ADD can do more. It can automatically extract compressed files and even fetch files from remote URLs.

How ADD Works

A simple ADD command looks like this:

ADD ./source_file.tar.gz /destination_folder

Here, ADD not only copies the file source_file.tar.gz but also automatically extracts it into /destination_folder. This is something COPY does not do.

Additional Features of ADD

Auto Extraction: If the source is a compressed file (for example, a .tar or .tar.gz file), ADD will automatically extract its contents into the destination directory.
Remote URLs: ADD can copy files from a remote URL. For example, you could write:

  ADD https://example.com/file.txt /destination_folder/file.txt

However, using ADD with URLs is not always recommended because it can make your build less predictable.

When to Use ADD

Extracting Archives: Use ADD when you need to automatically extract an archive during the image build.
Downloading Files: If you really need to fetch a file from a URL (although it is better to use a separate script for this task), ADD can do that.

Key Differences Between COPY and ADD

Even though both COPY and ADD copy files into an image, they are not the same. Here are the key differences:

Functionality:
- COPY simply copies files or directories. It does not do any extra processing.
- ADD copies files and can also extract compressed files. It may also fetch files from URLs.
Usage Clarity:
- COPY is clear and simple. It is the best choice if you only need to move files.
- ADD has extra features that can make your Dockerfile less obvious. It is best used only when its extra functions are needed.
Image Layer Creation:
- Both commands create image layers. However, using ADD to extract archives may result in more layers or a larger image if not managed carefully.
Best Practices:
- For most cases, it is best to use COPY because it is more predictable.
- Use ADD only if you need to extract an archive or download a file. Avoid using ADD for simple file copying tasks.

Choosing the right command can help in keeping your image simple and efficient. For more on how Docker images are created and why commands matter, see the process of creating Docker images.

Code Examples

Let’s look at some examples that show the difference between COPY and ADD.

Example with COPY

Suppose you have a directory called app/ in your project. You want to copy it to your image. Your Dockerfile might include:

FROM node:14
WORKDIR /usr/src/app
COPY ./app /usr/src/app
RUN npm install
CMD ["npm", "start"]

This Dockerfile uses COPY to move the app folder into the image. It is simple and does one task.

Example with ADD

Now, imagine you have an archive file called app.tar.gz. You want the contents of this archive in the image. Your Dockerfile can include:

FROM node:14
WORKDIR /usr/src/app
ADD ./app.tar.gz /usr/src/app
RUN npm install
CMD ["npm", "start"]

With ADD, Docker will automatically extract app.tar.gz into the working directory. This is convenient if you need to extract compressed files.

Best Practices When Using COPY and ADD

As a beginner, it is important to follow best practices. Here are some tips:

Prefer COPY Over ADD:

Use COPY when you only need to copy files or directories. It is more predictable and easier to understand.
Use ADD Only for Its Extra Features:

Use ADD when you need to extract a compressed file automatically or when you have a strong reason to download a file from a URL. For normal file copying, COPY is sufficient.
Keep Your Dockerfile Simple:

Simple Dockerfiles are easier to maintain. The more complicated your Dockerfile is, the harder it can be to troubleshoot.
Be Aware of Image Layers:

Every instruction in a Dockerfile creates a new layer. Using ADD to extract files may result in more layers than necessary. For tips on keeping your image efficient, check out optimizing Docker images.
Document Your Choices:

Comment in your Dockerfile why you chose COPY or ADD. This is helpful for other developers who read your file.

Impact on Docker Image Layers

Each command in a Dockerfile creates a new image layer. This is very important because layers affect the size and performance of your image. Using COPY and ADD in the right way can make your image smaller and faster.

When you use COPY, the file is simply added to the image as a new layer. With ADD, if you extract a file, the resulting files are also added as new layers. Understanding these layers can help in optimizing your build process. For more detailed information on image layers, you can read this article on Docker image layers.

How the Build Process Works

The Docker build process reads the Dockerfile line by line. Each instruction adds a new layer on top of the previous ones. This process is very important for both COPY and ADD.

For example, if you change a file that was copied with COPY, Docker may be able to use a cached layer for the earlier commands. This speeds up the build process. When using ADD to extract an archive, changes in the archive may force a rebuild of that layer, which can slow down the build.

It is helpful to understand the build process. If you are curious about how images are built, this explanation of Docker image creation can provide you with more details.

When to Use COPY vs. ADD

In summary, here is a simple guideline for choosing between COPY and ADD:

Use COPY:
- When you need to copy files or directories from your build context to the image.
- When you do not need to extract files or download content.
- When you want a simple and clear Dockerfile.
Use ADD:
- When you have a compressed file (such as a .tar or .tar.gz) and you want it automatically extracted.
- When you have a special need to download files from a URL (though this is not common and may lead to unpredictable builds).

This guideline can help keep your Dockerfiles clean and your images efficient.

Real-World Example

Imagine you have a web application project. Your project folder has a directory called src/ with your source code and a compressed file called static_files.tar.gz that contains static assets.

Using COPY for the Source Code

Your Dockerfile might start like this:

FROM python:3.9
WORKDIR /app
COPY ./src /app/src
RUN pip install -r requirements.txt
CMD ["python", "app.py"]

Here, COPY is used to move your source code to the image. The source code is not compressed, so no extraction is needed.

Using ADD for Static Files

Now, you want the static assets to be unpacked automatically. You can add the following line in your Dockerfile:

ADD ./static_files.tar.gz /app/static

This line will copy the static_files.tar.gz file and extract its contents into /app/static. Now, your web server can serve the static assets from that folder.

Using both COPY and ADD in one Dockerfile can be useful. Just remember to use ADD only when you need its extra capabilities.

Tips for Beginners

Practice is Important:

Try different Dockerfiles with COPY and ADD. See how changes affect your image. Experimenting helps you understand the impact of each command.
Keep Learning:

Docker is a powerful tool and there is always more to learn. If you are new to Docker, reading more guides can help. For instance, learning how Docker images are built can be very useful.
Read Documentation:

The official Docker documentation and online tutorials are great resources. They can show you the best practices and common pitfalls.
Simplify Your Dockerfile:

Avoid using extra features if they are not needed. The simpler your Dockerfile, the easier it is to maintain and debug.
Optimize Your Build:

Every instruction in a Dockerfile creates an image layer. Use COPY when possible to keep your image lean. This is important for performance. For more tips, check out optimizing Docker images for performance.

Conclusion

Understanding the difference between the COPY and ADD commands is important when working with Dockerfiles. Both commands are used to bring files from your host system into the Docker image. However, they have key differences:

COPY is simple and copies files or directories exactly as they are.
ADD does more by extracting compressed files and downloading content from URLs.

For most situations, it is best to use COPY for clarity and simplicity. Use ADD only when you need its extra features, such as automatic extraction of archives.

Knowing which command to use can help you build more efficient Docker images. It can also make your Dockerfile easier to understand for other developers. Remember, each command in a Dockerfile creates a new layer, so keeping your instructions simple can lead to better performance.

By following these guidelines and best practices, you will build Docker images that are clean and efficient. As you get more comfortable with Docker, you can experiment with more advanced techniques. For a deeper look at how Docker images work, you might also review how Docker images are created.

I hope this article helps you understand the differences between COPY and ADD. Keep practicing and experimenting with your Dockerfiles. Learning by doing is the best way to improve. Happy containerizing!

DEV Community