4.2.3 COPY

COPY is the Dockerfile instruction used to bring files and directories from the build context into the image's filesystem, producing a new layer containing exactly the copied content at the specified destination path.

Basic Usage

COPY takes a source path (relative to the build context) and a destination path (inside the image), copying the specified content from one to the other during the build.

COPY app.py /app/app.py
COPY src/ /app/src/

The first copies a single file; the second copies an entire directory's contents into the specified destination.

Copying Into the Current Working Directory

When WORKDIR has already been set, COPY destinations can be expressed relative to it, which is a common and concise pattern.

WORKDIR /app
COPY . .

This copies the entire build context into /app, relying on the previously established working directory rather than spelling out the absolute destination path.

Wildcard Patterns in Source Paths

COPY supports basic wildcard patterns for selecting multiple matching files without listing each one individually.

COPY *.json ./

This copies every file in the build context ending in .json to the current working directory inside the image.

Why COPY Is Preferred Over ADD for Simple Cases

COPY does only one thing — copying files — with no additional behavior like automatic archive extraction or remote URL fetching, which makes its behavior easier to predict and reason about compared to ADD's broader feature set.

COPY archive.tar.gz /app/

ADD archive.tar.gz /app/

The first copies the archive file as-is; the second would automatically extract it, a meaningful behavioral difference that is easy to overlook if not understood explicitly.

Why COPY Matters

COPY is the primary mechanism by which an application's actual source code and files become part of an image, making it one of the most frequently used and most consequential instructions in nearly every Dockerfile.