Gera Tools

Dockerfile Instructions Reference

All Dockerfile instructions with syntax, effect on layers and best-practice notes.

Searchable reference for every Dockerfile instruction — FROM, RUN, COPY, ADD, ENV, ARG, EXPOSE, CMD, ENTRYPOINT, HEALTHCHECK and more — with syntax, whether each creates an image layer, and practical best-practice notes.

Which Dockerfile instructions create a new image layer?

RUN, COPY and ADD each commit a new filesystem layer. FROM starts a stage without adding a layer, and metadata instructions like ENV, CMD, ENTRYPOINT, LABEL and EXPOSE change image configuration without creating a filesystem layer.

Dockerfile instructions at a glance

A Dockerfile is an ordered list of instructions that the Docker builder turns into an image. This reference lists every instruction with its exact syntax, whether it creates a new filesystem layer, and a best-practice note. Search the table to jump straight to the instruction you need.

How it works

Docker images are built as a stack of read-only layers. The builder reads your Dockerfile top to bottom and, for layer-creating instructions, runs the step inside a temporary container and commits the resulting filesystem diff as a new layer. Three instructions create layers — RUN, COPY and ADD — so the order and grouping of those lines directly controls image size and cache reuse.

Other instructions only change image configuration (metadata) rather than the filesystem: ENV, ARG, CMD, ENTRYPOINT, EXPOSE, LABEL, WORKDIR, USER, VOLUME, HEALTHCHECK, STOPSIGNAL, SHELL and ONBUILD. FROM is special — it begins a build stage by selecting a base image without adding a layer of its own.

Each instruction is also a cache key. If nothing above a line changed, Docker reuses the cached layer. That is why you copy and install dependencies before copying application source: dependency layers stay cached across code edits.

Tips and examples

  • Combine related shell steps in a single RUN with && and clean package caches in the same line so the cleanup lands in the same layer:
RUN apt-get update \
 && apt-get install -y --no-install-recommends curl \
 && rm -rf /var/lib/apt/lists/*
  • Pair ENTRYPOINT with CMD for a sensible default that callers can override:
ENTRYPOINT ["python", "app.py"]
CMD ["--port", "8080"]
  • Use multi-stage builds and COPY --from=builder to ship only compiled artifacts, keeping the runtime image small.
  • Run as a non-root USER, add a HEALTHCHECK, and label images with the org.opencontainers.image.* convention for traceability.