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

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:

​
2. Using ADD for a Local Directory

Functionally identical to COPY when the source is a directory:

​
3. ADD to Extract a Local Archive

Automatically unpack app.tar.xz into /testdir:

​
Consolidating Steps with RUN

Multiple RUN instructions add layers. Combine download, extraction, build, and cleanup in one RUN to keep images small:
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:
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