Dockerfile Reference
Last reviewed on 2026-09-25
Every Dockerfile instruction and docker build flag, with syntax, examples, and the behaviour that trips people up
This is the Dockerfile reference for people who already have a build running and need to know exactly what an instruction does. Every page below covers one instruction or one docker build flag: the syntax, the options, what it does to the image, and how it interacts with the layer cache.
A Dockerfile is read top to bottom. It must begin with FROM, which fixes the base image and opens a build stage. Instructions that change the filesystem — RUN, COPY, ADD — each produce a layer. Instructions that only record metadata — ENV, WORKDIR, USER, LABEL, CMD, ENTRYPOINT, HEALTHCHECK — do not.
New to this? Start with the docker build command reference, then read build context and .dockerignore — together they explain most surprising build behaviour.
Dockerfile cheat sheet
Every instruction on one screen. Linked instructions have a full reference page.
| Instruction | What it does | Example |
|---|---|---|
FROM | Start a build stage from a base image | FROM python:3.12-slim AS build |
RUN | Run a command and commit the result as a layer | RUN apt-get update && apt-get install -y curl |
COPY | Copy files from the context or another stage | COPY --chown=app:app . /app |
ADD | Copy with URL download and tar auto-extraction | ADD app.tar.gz /opt/ |
WORKDIR | Set (and create) the working directory | WORKDIR /app |
ARG | Build-time variable, set with --build-arg | ARG VERSION=1.0 |
ENV | Environment variable kept in the image | ENV NODE_ENV=production |
USER | User for later RUN steps and the container | USER 10001:10001 |
EXPOSE | Document the port the app listens on | EXPOSE 8080 |
VOLUME | Declare a mount point for persistent data | VOLUME /data |
ENTRYPOINT | Executable the container always runs | ENTRYPOINT ["/app/server"] |
CMD | Default command or arguments, replaced by docker run args | CMD ["--port", "8080"] |
HEALTHCHECK | Command Docker runs to test the container | HEALTHCHECK CMD curl -f http://localhost/ || exit 1 |
LABEL | Image metadata (OCI annotations) | LABEL org.opencontainers.image.source="https://github.com/o/r" |
SHELL | Change the shell used by shell-form commands | SHELL ["/bin/bash", "-o", "pipefail", "-c"] |
STOPSIGNAL | Signal sent to stop the container | STOPSIGNAL SIGTERM |
ONBUILD | Instruction deferred to images built FROM this one | ONBUILD COPY . /app |
Quick answers
Which Dockerfile instruction begins a new build stage and selects a base image?
FROM. Every FROM starts a new build stage and sets its base image, and a Dockerfile must begin with one (only ARG, comments and parser directives may come before it). Name a stage with FROM image AS name to copy from it later. See the FROM reference.
How does Docker know when to use the cache during a build and when not?
For each instruction, Docker looks for an existing layer built from the same parent layer with the same instruction text. For COPY and ADD it also compares a checksum of the copied files' contents. RUN is only compared by its command string, so outside changes (a new package version) do not break the cache. Once one step misses, every step after it is rebuilt. See layer caching.
What is the difference between CMD and ENTRYPOINT?
ENTRYPOINT sets the executable that always runs. CMD sets default arguments (or a default command) that docker run image args replaces. With both in exec form, the container runs ENTRYPOINT followed by CMD. See ENTRYPOINT and CMD.
What is the difference between COPY and ADD?
COPY copies files from the build context or another stage. ADD also fetches remote URLs and Git repositories and auto-extracts local tar archives. Use COPY unless you need one of those extras. See COPY.
What is the difference between ARG and ENV?
ARG exists only while the image builds and is set with --build-arg. ENV is saved in the image and visible to the running container. Neither is safe for secrets; use RUN --mount=type=secret instead. See ARG.
How do I run the container as a non-root user?
Create a user in the Dockerfile, then add USER 10001:10001 (a numeric UID) before CMD/ENTRYPOINT. At runtime, docker run --user and docker exec -u override it. See the USER reference.
Dockerfile Instructions
FROM
Sets the base image for subsequent instructions. The first instruction in a Dockerfile must be FROM.
View documentation →COPY
Copies files or directories from source to the filesystem of the container at the specified path.
View documentation →RUN
Executes commands in a new layer on top of the current image and commits the results.
View documentation →CMD
Provides default commands and arguments for an executing container. There can only be one CMD per Dockerfile.
View documentation →ENTRYPOINT
Sets the executable the container runs. Exec vs shell form, how it combines with CMD, and passing arguments.
View documentation →ENV
Sets environment variables in the image for both building and runtime of the containerized application.
View documentation →HEALTHCHECK
Configure a probe so Docker can tell whether your container is still working. Covers options, exit codes, and tuning.
View documentation →USER
Drop privileges in your image. How to create and use a non-root user, with file-ownership pitfalls and distroless caveats.
View documentation →ARG
Declare build-time variables and pass them with --build-arg. Scope across stages, defaults, and why ARG must not hold secrets.
View documentation →WORKDIR
Set the working directory for RUN, CMD, ENTRYPOINT, COPY and ADD. Relative-path behaviour and the mistakes to avoid.
View documentation →ADD
Copy files with extras: remote URLs, checksum verification, and automatic archive extraction. When to prefer COPY instead.
View documentation →LABEL
Attach metadata to an image, including the OCI annotation keys registries and scanners read.
View documentation →Build Concepts
Multi-stage Builds
Create smaller and more efficient images by using multiple stages to separate build and runtime environments.
View documentation →Build Context
Understand the build context, the set of files available to Docker during the build process.
View documentation →Layer Caching
Learn how Docker's build cache works and how to optimize your builds for better caching.
View documentation →.dockerignore
Pattern syntax, precedence, and common mistakes for the file that filters your build context.
View documentation →Command Line Reference
docker build
Build an image from a Dockerfile with detailed options and examples.
View documentation →docker image
Manage Docker images, including listing, tagging, and removing images.
View documentation →docker build -t
Name and tag an image at build time. Tag format rules, multiple -t flags, registry prefixes, and what :latest really means.
View documentation →docker build -f
Build from a Dockerfile that is not called Dockerfile or does not sit in the context root. Paths, monorepos, and stdin.
View documentation →