A Dockerfile is a text-based script of sequential instructions for building Docker container images, living at the heart of containerization workflows and enabling developers to package applications with all dependencies into portable, reproducible runtime environments. Every instruction creates a layer—understanding layer mechanics, caching behavior, and optimization strategies is critical for lean, fast, and secure images. Modern Dockerfile authoring relies on multi-stage builds, BuildKit features like cache mounts and heredocs, and security practices such as non-root execution, minimal base images, and supply chain attestations. The key mental model: treat your Dockerfile as production code—every line impacts image size, build speed, security posture, and runtime behavior.
What This Cheat Sheet Covers
This topic spans 14 focused tables and 108 indexed concepts. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.
Table 1: Parser Directives
Parser directives are special comments that must appear at the very top of a Dockerfile—before any instruction, blank line, or regular comment—and configure how BuildKit processes the file. They are silently ignored if placed later, with no error; always place them as the file's first lines.
| Directive | Example | Description |
|---|---|---|
# syntax=docker/dockerfile:1 | • Declares the Dockerfile frontend version, enabling latest v1.x features (heredocs, build checks, cache mounts) without upgrading Docker Engine • recommended for every Dockerfile—ensures consistent builds across all CI and local environments. | |
# escape=` | • Changes the default \ escape character to another character• set to backtick on Windows where backslash is the path separator, preventing ambiguity in COPY and RUN path strings. | |