Dockerfile Reference
Last reviewed on 2026-05-02
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 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
Configures a container that will run as an executable, and allows you to configure a container to run as an executable.
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 →