COPY Instruction Reference
Copy files and directories from the build context to the image
Syntax
The COPY instruction copies files or directories from the build context to the filesystem of the container at the specified path.
The COPY instruction is one of the most commonly used Dockerfile instructions. It allows you to copy files and directories from your build context (the directory you're building from) into your Docker image.
The COPY instruction creates a new layer in your Docker image, which will contain the copied files. Multiple source files can be specified, and each source must be relative to the build context (the location of your Dockerfile).
Description
The COPY instruction copies new files or directories from <src> and adds them to the filesystem of the container at the path <dest>. Multiple <src> resources may be specified, but the paths must be relative to the source directory (the build context).
Each <src> may contain wildcards and matching will be done using Go's filepath.Match rules. For example:
COPY hom* /mydir/ # copies all files starting with "hom"
COPY hom?.txt /mydir/ # ? is replaced with any single character
COPY *.txt /mydir/ # copies all files with .txt extensionThe <dest> is an absolute path, or a path relative to WORKDIR, into which the source will be copied inside the destination container.
COPY test.txt /absoluteDir/
COPY test.txt relativeDir/If <dest> doesn't exist, it is created including all missing directories in its path.
Examples
Basic Usage
Copy a single file from your build context to a directory in the image:
FROM alpine:3.14
WORKDIR /app
COPY package.json .This copies package.json from the build context to /app/package.json in the image.
Copying Multiple Files
Copy multiple files at once:
FROM node:18-alpine
WORKDIR /app
COPY package.json package-lock.json ./This copies both package.json and package-lock.json to the /app directory.
Using Wildcards
Copy multiple files using wildcards:
FROM python:3.9-slim
WORKDIR /app
COPY *.py ./This copies all Python files from the build context to the /app directory.
Copying Directories
Copy an entire directory and its contents:
FROM node:18-alpine
WORKDIR /app
COPY src/ ./src/This copies the src directory and all its contents to /app/src/ in the image.
Setting Ownership
Copy files and set their ownership:
FROM ubuntu:20.04
WORKDIR /app
COPY --chown=node:node . .This copies all files from the build context to /app and sets their ownership to the node user and group.
Setting Permissions
Copy a file and set specific permissions:
FROM alpine:3.14
WORKDIR /app
COPY --chmod=755 entrypoint.sh .This copies entrypoint.sh to /app and sets its permissions to 755 (executable).
Multi-stage Build
Copy files from one build stage to another:
FROM node:18 AS build
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/htmlThis copies the built files from the build stage to the nginx image.
Best Practices
- Use COPY instead of ADD for simple file copying. Use ADD only when you need its tar extraction or remote URL features.
- Be specific with what you copy. Avoid using COPY . . as it copies everything in your build context, which can make your image unnecessarily large.
- Place COPY instructions after installing dependencies to take advantage of Docker's build cache. Files that change frequently should be copied later in the Dockerfile.
- Use .dockerignore to exclude files and directories that shouldn't be copied into your image.
- Use multi-stage builds with COPY --from to create smaller production images.
- Consider using non-root users with --chown for better security.
Notes and Limitations
- The COPY instruction creates a new layer in your Docker image.
- COPY honors .dockerignore, which can be used to exclude files and directories from being copied.
- COPY can only copy from the build context or from previous build stages. It cannot copy from remote URLs or extract archives (use ADD for those features).
- The --chown feature only works on Linux containers, not Windows.
- If you're using a Windows container, the destination paths should use Windows-style backslashes, but they'll be converted to forward slashes in the Dockerfile.