Docker ADD vs COPY: Key Differences and Best Practices

If you are habitual of using Dockerfiles for building container images, you must have come across Docker instructions ADD and COPY. They both provide a similar function, in the sense that they both allow the user to get folders and files into your images at build time. 

So what should you use?

In this guide, we shall put the debate Docker ADD vs COPY to rest!

So let’s get to it! 

Understanding the Syntax

Let’s learn more about the syntax and examples of both; ADD and COPY. 

ADD Syntax

The ADD command in Dockerfile is used to copy files or directories from a source to the image file. It can also compress files directly into the destination. 

Syntax:

ADD [source] [destination]

• Source: the path to the directory or the file on the host or the URL.
• Destination: the path inside Docker image where the file or the directory will be copied. 

Example Code:

ADD myapp.tar.gz /usr/src/app/

This command copies and extracts myapp.tar.gz (the source) into /usr/src/app/ (destination).

COPY Syntax 

The COPY command is much simpler and is only used for copying directories and paths from the build context to the image file. Unlike ADD, it does not extract files or handle URL queries. 

Syntax:

COPY [source] [destination]

• Source: the relative path to the directory or the file within the build context.
• Destination: the path inside Docker image where the file or the directory will be copied. 

Example Code:

COPY app/ /usr/src/app/

This command copies the entire app (the source) into /usr/src/app/ (destination).

Why Use COPY Instead of ADD in Dockerfile?

In most cases, COPY is preferred instead of ADD in most case scenarios due to its easy nature, security, and clear intent. So let’s do a quick Docker ADD vs COPY battle: 

1. Simplicity & Clarity

COPY is straightforward since it only copies files or directories from the source into the image without functionality. Whereas, ADD is multi-featured, it handles file copying, archives extracting , and URL downloading, which can increase the complexity. 

Using COPY makes your Dockerfile easy to read and maintain. 

2. Security Considerations 

While ADD is more convenient since it can fetch files from the URL, it can expose your build process to external malicious files. COPY only interacts with files from the source, therefore, reducing attack surface and ensuring greater control over the input. 

3. Predictable Behavior 

COPY copies the files without altering them, whereas ADD extracts the files and handles URL, which might lead to unwanted behavior if not managed carefully. For example, if you use ADD for a compressed file, it might extract the contents instead of copying it. 

4. Best Practices 

Docker’s official documentation recommends using COPY unless you need to explicitly use the extra functionality from ADD. 

So when should we use ADD? 

There are two basic use case of using ADD instead of COPY:

• Archive Extraction: if you need to extract compressed files. 
• URL Handling: if you need to download a file from the URL. 

Docker ADD Vs COPY – Key Differences 

Aspect	ADD	COPY
Purpose	Used to copy files or directories and optionally extract compressed files (e.g., .tar).	Used to copy files or directories without additional functionality.
File Extraction	Supports automatic extraction of compressed files like .tar, .gz, or .bz2.	Does not extract compressed files; copies them as-is.
URL Support	Can fetch and copy files directly from a URL to the image.	Does not support URLs; works only within the Docker build context.
Complexity	More complex due to its additional features like file extraction and URL handling.	Simpler and focused solely on copying files.
Recommended Use Case	When file extraction or downloading from a URL is necessary.	For straightforward copying of files and directories from the build context.
Security Implications	Can introduce potential vulnerabilities by downloading files directly from URLs.	Safer as it only interacts with files within the Docker build context.
Performance	Slightly slower due to additional processing for extraction and URL handling.	Faster as it performs only basic file copying.

When to Use Docker ADD vs COPY? – Best Practices 

Understanding the use of Docker ADD vs COPY in Dockerfiles is essential for creating efficient, secure, and maintainable container images. Here are the best practices for Docker ADD vs COPY:

Use COPY When:

1. Copying Files & Directories

Use COPY for all straightforward file and directory transfers from source to image. Example Code:

COPY ./app /usr/src/app

2. Simplicity & Clarity 

When you only need to copy files without URL handling or file extraction. This makes sure that Dockerfile is easy to read and maintain. 

3. Security & Control

When you want to keep the build process restricted to known files to avoid vulnerabilities. 

Use ADD When:

1. Extracting Compressed Files

Use ADD to extract and copy files directly into the destination. Example Code:

ADD myapp.tar.gz /usr/src/app

2. Fetching Files from URLs

Use ADD when you want to directly download files from an external URL. Example Code: 

ADD https://example.com/file.tar.gz /usr/src/app/

Best Practices to Follow

Working with ADD and COPY is quite simple and straightforward. But it is best to follow these practices for Docker ADD vs COPY:

1. Default to COPY 

Always use COPY, unless you need ADD’s extra functionality, such as extraction and URL handling. 

2. Pre-Extract Archives When Possible 

If you don’t need dynamic extraction during the build, extract archives files locally before using COPY. 

3. Limit URL Dependencies 

Limit using ADD for URL downloads. Instead, use external tools like curl or wget within the RUN command. Example Code: 

RUN curl -o /usr/src/app/file.tar.gz https://example.com/file.tar.gz

4. Document your Commands

Include comments in your Dockerfile to explain why you need ADD over COPY. 

Docker ADD vs COPY: Common Pitfalls and How to Avoid Them

Here are a few common pitfalls and their solutions:

1. Misusing ADD for copying: Use COPY for all straightforward file transfers. 
2. Unintended file extraction: Use COPY for compressed files until needed. 
3. Security risks with URL: Use RUN curl or wget.
4. Including unnecessary files: Use a .dockerignore file to exclude irrelevant files. 
5. Overwriting files: Double-check paths to avoid accidents. 
6. Ignore file permissions: Use RUN chmod to set appropriate permissions. 
7. Lack of documentation: Add comments to clarify. 

Examples: Docker ADD vs COPY in Action

Scenario	ADD Example	COPY Example	Best Practice
Copying files/directories	ADD ./app /usr/src/app/	COPY ./app /usr/src/app/	Use COPY for clarity.
Extracting archives	ADD app.tar.gz /usr/src/app/	COPY app.tar.gz /usr/src/app/ + RUN tar	Use ADD for automatic extraction.
Downloading files from URLs	ADD https://example.com/file.tar.gz /tmp/	N/A: Use RUN curl	Use RUN curl for better control.
Managing excluded files	Supports .dockerignoreimplicitly	Supports .dockerignoreimplicitly	Use .dockerignore to exclude unnecessary files.
Avoiding accidental overwrites	Ensure correct paths	Ensure correct paths	Double-check file paths and use comments.

Conclusion: Choosing the Right Command in Docker ADD vs COPY

According to the best practices, it is better to use COPY instead of ADD due to straightforward processes and no security implications. Unless explicitly needed, it is best to avoid ADD command! 

Frequently Asked Questions