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.
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/
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:
- 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.
- 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.
- 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.
- 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:
- Copying Files & Directories
Use COPY for all straightforward file and directory transfers from source to image. Example Code:
COPY ./app /usr/src/app
- 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.
- Security & Control
When you want to keep the build process restricted to known files to avoid vulnerabilities.
Use ADD When:
- Extracting Compressed Files
Use ADD to extract and copy files directly into the destination. Example Code:
ADD myapp.tar.gz /usr/src/app
- 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:
- Default to COPY
Always use COPY, unless you need ADD’s extra functionality, such as extraction and URL handling.
- Pre-Extract Archives When Possible
If you don’t need dynamic extraction during the build, extract archives files locally before using COPY.
- 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
- 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:
- Misusing ADD for copying: Use COPY for all straightforward file transfers.
- Unintended file extraction: Use COPY for compressed files until needed.
- Security risks with URL: Use RUN curl or wget.
- Including unnecessary files: Use a .dockerignore file to exclude irrelevant files.
- Overwriting files: Double-check paths to avoid accidents.
- Ignore file permissions: Use RUN chmod to set appropriate permissions.
- 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
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.