DockerFile COPY vs ADD – A Complete Guide with Examples & Best Practices

Introduction – Why Learn COPY and ADD Instructions in Docker?

When building Docker images, it’s essential to include application files, configuration scripts, and dependencies from your local environment into the container. Docker offers two main instructions for this: COPY and ADD.

While they may appear similar, they serve slightly different purposes. This guide explores the differences, use cases, syntax, and best practices for using COPY and ADD effectively in your Dockerfiles.

In this article, you’ll learn:

• The difference between COPY and ADD
• How and when to use each command
• Real-world examples
• Best practices and functional comparison

What is the COPY Command in DockerFile?

The COPY instruction is used to copy files or directories from your local build context into the Docker image.

Syntax:

COPY <src> <dest>

Example:

COPY index.html /usr/share/nginx/html/

This copies index.html from your local project into the image directory /usr/share/nginx/html/.

What is the ADD Command in DockerFile?

The ADD instruction includes all the features of COPY with extra capabilities, such as:

• Extracting local .tar or .tar.gz archives
• Downloading files from remote URLs

Syntax:

ADD <src> <dest>

Examples:

1. Copying a File (like COPY):

ADD index.html /usr/share/nginx/html/

2. Extracting a Compressed Archive:

ADD assets.tar.gz /app/

Automatically extracts contents into /app/.

3. Downloading from a URL:

ADD https://example.com/image.png /images/

Downloads and adds the file to /images/.

Difference Between COPY and ADD

Best Practice: Always use COPY unless you explicitly need the additional features of ADD.

Best Practices for Using COPY and ADD

• Prefer COPY for simple file/directory transfers.
• Avoid using ADD for remote downloads. Use curl or wget inside a RUN command instead.
• Use ADD only for extracting local archives (.tar, .tar.gz).
• Use .dockerignore to exclude unnecessary files from the build context.

Practical Example – Using Both

FROM python:3.11

WORKDIR /app

# Copy all source code into the container
COPY . .

# Extract an archive – ADD is required here
ADD data-files.tar.gz /data/

# Install dependencies
RUN pip install -r requirements.txt

CMD ["python", "main.py"]

Summary Table – COPY vs ADD

Functional Comparison Table

Final Thoughts

Both COPY and ADD are useful for including files in your Docker image—but they are not interchangeable. Stick to COPY for routine operations and use ADD only when its extra capabilities (like archive extraction or remote fetch) are truly needed.

Pro Tip: Use a .dockerignore file to keep your image lean and avoid copying unwanted files.

FAQ – Frequently Asked Questions

Q1: Can COPY copy files from remote URLs?
No. COPY only works with local files. Use ADD or tools like curl.

Q2: Should I always use COPY instead of ADD?
Yes, unless you need to extract an archive or fetch a file from a URL.

Q3: What happens if a .tar file is corrupted when using ADD?
Docker will throw an error. Ensure the archive is valid and in a supported format.

Q4: How do I exclude files from being copied in COPY/ADD?
Use a .dockerignore file:

node_modules/
*.log
.env

Q5: Can COPY and ADD copy hidden files?
Yes, as long as they’re not excluded in .dockerignore.

Q6: Can I copy multiple files using one instruction?
Yes:

COPY app.py requirements.txt /app/

Q7: Is there any performance difference between COPY and ADD?
️ Very minor. But COPY is generally faster and more transparent for simple tasks.