Skip to main content
In this guide, we’ll compare the COPY and ADD directives in a Dockerfile, highlight their differences, and share best practices for keeping your images predictable and lean.

​
Why It Matters

Both COPY and ADD bring files and directories from your build context into the container’s filesystem. However, ADD has two extra behaviors that can be surprising:
  • Automatic extraction of local archives
  • Remote URL download at build time
By understanding these differences, you can write clearer Dockerfiles and avoid unintended side effects.

​
Feature Comparison

DirectiveCopies Local Files/DirsExtracts Local ArchivesDownloads Remote URLs
COPY✔️❌❌
ADD✔️✔️✔️
Overusing ADD can introduce unexpected files or extra layers. If you only need to transfer files, prefer COPY.

​
Simple Usage Examples

​
1. Using COPY

A straightforward copy of testdir from your context into the image: 
FROM centos:7
COPY testdir /testdir

​
2. Using ADD for a Local Directory

Functionally identical to COPY when the source is a directory: 
FROM centos:7
ADD testdir /testdir

​
3. ADD to Extract a Local Archive

Automatically unpack app.tar.xz into /testdir: 
FROM centos:7
ADD app.tar.xz /testdir

​
Consolidating Steps with RUN

Multiple RUN instructions add layers. Combine download, extraction, build, and cleanup in one RUN to keep images small: 
FROM centos:7

RUN curl -fsSL http://example.com/app.tar.xz \
    | tar -xJ -C /testdir \
    && cd /testdir \
    && yarn build
This single-layer approach removes the archive stream in-flight, leaving no temporary files behind.

​
When You Need ADD for Remote Files

If you prefer ADD to fetch a URL, then extract manually: 
FROM centos:7

# Downloads to /testdir/app.tar.xz
ADD http://example.com/app.tar.xz /testdir

# Extract & build in a separate step
RUN tar -xJf /testdir/app.tar.xz -C /tmp/app \
    && make -C /tmp/app
For clarity and layer reduction, consider using a single RUN with curl and tar instead of ADD.

​
Best Practices

  • Use COPY for straightforward file and directory transfers.
  • Reserve ADD for:
    • Local archive auto-extraction (.tar, .tar.gz, etc.).
    • Quick remote downloads without further processing.
  • Combine commands in a single RUN to minimize image layers and overall size.

Watch Video