Docker ADD vs COPY: Key Differences and Best Practices

Docker ADD vs COPY

Table of Contents

Get up to 50% off now

Become a partner with CyberPanel and gain access to an incredible offer of up to 50% off on CyberPanel add-ons. Plus, as a partner, you’ll also benefit from comprehensive marketing support and a whole lot more. Join us on this journey today!

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. 

Tech Delivered to Your Inbox!

Get exclusive access to all things tech-savvy, and be the first to receive 

the latest updates directly in your inbox.

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/

Enhance Your CyerPanel Experience Today!
Discover a world of enhanced features and show your support for our ongoing development with CyberPanel add-ons. Elevate your experience today!

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. 

  1. 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. 

  1. 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. 

  1. 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 

AspectADDCOPY
PurposeUsed to copy files or directories and optionally extract compressed files (e.g., .tar).Used to copy files or directories without additional functionality.
File ExtractionSupports automatic extraction of compressed files like .tar, .gz, or .bz2.Does not extract compressed files; copies them as-is.
URL SupportCan fetch and copy files directly from a URL to the image.Does not support URLs; works only within the Docker build context.
ComplexityMore complex due to its additional features like file extraction and URL handling.Simpler and focused solely on copying files.
Recommended Use CaseWhen file extraction or downloading from a URL is necessary.For straightforward copying of files and directories from the build context.
Security ImplicationsCan introduce potential vulnerabilities by downloading files directly from URLs.Safer as it only interacts with files within the Docker build context.
PerformanceSlightly 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

  1. 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. 

  1. 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

  1. 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. 

  1. Pre-Extract Archives When Possible 

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

  1. 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

  1. 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

ScenarioADD ExampleCOPY ExampleBest Practice
Copying files/directoriesADD ./app /usr/src/app/COPY ./app /usr/src/app/Use COPY for clarity.
Extracting archivesADD app.tar.gz /usr/src/app/COPY app.tar.gz /usr/src/app/ + RUN tarUse ADD for automatic extraction.
Downloading files from URLsADD https://example.com/file.tar.gz /tmp/N/A: Use RUN curlUse RUN curl for better control.
Managing excluded filesSupports .dockerignoreimplicitlySupports .dockerignoreimplicitlyUse .dockerignore to exclude unnecessary files.
Avoiding accidental overwritesEnsure correct pathsEnsure correct pathsDouble-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

1. What happens if I use ADD to copy files without an archive?

If the source file is not an archive, ADD it it functions similarly to COPY but still adds unnecessary complexity. Prefer COPY in such cases.

2. Can I use both ADD and COPY in the same Dockerfile?

Yes, you can use both commands in the same Dockerfile based on specific requirements, but ensure each command is justified to maintain clarity.

3. How do ADD and COPY impact build performance?

COPY is generally faster and more efficient as it avoids unnecessary processing like archive extraction. Use COPY when extra features of ADD are not required.

4. When is ADD a better option in a Dockerfile?

ADD is better when you need to extract compressed files automatically or download files directly from a URL into the image.

Marium Fahim
Hi! I am Marium, and I am a full-time content marketer fueled by an iced coffee. I mainly write about tech, and I absolutely love doing opinion-based pieces. Hit me up at [email protected].
Unlock Benefits

Become a Community Member

SIMPLIFY SETUP, MAXIMIZE EFFICIENCY!
Setting up CyberPanel is a breeze. We’ll handle the installation so you can concentrate on your website. Start now for a secure, stable, and blazing-fast performance!