What does the `# syntax=docker/dockerfile:1` line at the top of a Dockerfile do?

### What that line actually is `# syntax=docker/dockerfile:1` looks like a comment, and to anything that is not BuildKit it *is* a comment. To BuildKit it is a **parser directive**: a small, fixed set of `# key=value` lines that must appear at the very top of a Dockerfile, before any build instruction and before any ordinary comment. Once a normal comment or an instruction has been seen, the parser stops looking for directives and every later `# syntax=` line is treated as plain text — which is the single most common reason the pin appears to do nothing. The directive's value is an **image reference**: a container image that BuildKit will pull and run as the build's *frontend*. ### What a frontend is BuildKit itself does not understand Dockerfiles. It understands LLB, a graph of build operations. A frontend is the component that converts some build definition into LLB, and the Dockerfile frontend — published as `docker/dockerfile` — is the one that converts Dockerfile syntax. BuildKit ships with a copy of that frontend compiled in, which is what you get when the directive is absent. When the directive is present, BuildKit fetches the named image from a registry, runs it as a short-lived container, hands it the Dockerfile and the build's parameters, and takes back the LLB it produces. The image is cached after the first pull, so the cost is paid once per builder, not once per build. ### Why anyone bothers Decoupling. The Dockerfile language grows independently of the Docker Engine. Heredoc bodies on `RUN` and `COPY`, `COPY --link`, `ADD --checksum`, additional `RUN --mount` types and other syntax all arrived in frontend releases. With the pin, a machine running an older engine can still build a Dockerfile that uses recent syntax, because the parser doing the work comes from the registry rather than from the installed binary. Without the pin you are limited to whatever the local BuildKit was compiled with, and a Dockerfile using newer syntax fails with a parse error on some machines and succeeds on others — the classic "works on my laptop" build failure. ### Choosing the tag `docker/dockerfile:1` is the tag almost everyone should use. It is a moving major-version tag: it resolves to the newest 1.x.y release, which is maintained as backwards compatible, so you get new syntax and fixes without editing thousands of Dockerfiles. `docker/dockerfile:1.7` narrows to a minor line, and a full `1.7.0` or a digest pins exactly — the right choice when a regulated pipeline needs bit-identical build inputs, at the cost of manual bumps. There is also a `-labs` channel (`docker/dockerfile:1-labs`) carrying experimental features that are not in the stable frontend; treat anything you use from it as subject to change. ### What it unlocks, concretely The most visible feature is heredoc support, which turns a wall of backslash continuations into an ordinary shell script inside the Dockerfile: ```dockerfile # syntax=docker/dockerfile:1 FROM alpine:3.20 RUN <<EOF set -eux apk add --no-cache curl ca-certificates adduser -D -u 10001 app EOF USER app ``` The body runs in a single `RUN`, so it is still one layer, and `set -eux` gives you failure-on-error and a trace without repeating `&& \` on every line. `COPY <<EOF /etc/app/config.ini` writes an inline file the same way. ### The operational edges **The frontend is code you execute.** BuildKit pulls that image and runs it as part of every build. It comes from Docker Hub by default. In an environment that cares about supply chain, mirror it into your own registry, reference it there, and decide deliberately how often the mirror is refreshed — a floating `:1` tag means a build today can use a frontend that did not exist last week. **It needs to be reachable.** On an air-gapped or heavily firewalled builder, an unmirrored `# syntax=` line turns every build into a failed image pull. Either mirror the frontend or drop the directive and accept the built-in parser's feature set. **The classic builder ignores it entirely.** Build the same file with `DOCKER_BUILDKIT=0` and the line is just a comment, so any syntax it was enabling fails to parse. That is a useful tell when one CI job fails and another succeeds on the same Dockerfile. **It is per-file, not per-project.** The directive lives in each Dockerfile. Adding it to one file changes nothing about the others, which is why partial adoption across a repository produces builds that behave differently file by file.