Comments (#)

# Dockerfile: comment — everything from # to the end of the line is a comment.
# Write at the start of a line.

# For multi-line comments, put # at the start of each line.
# Dockerfile has no multi-line comment syntax like /* */.

# Parser directives (not comments — they change how the Dockerfile is interpreted):
# # syntax=docker/dockerfile:1.4
# # escape=`

FROM ubuntu:22.04

# Inline comments are not supported. The # below is at the start of a line only.
RUN apt-get update     # This causes an error (inline comments are not allowed)

Parser directives are special instructions written at the very top of a Dockerfile using the same # key=value syntax as comments. They modify the behavior of the parser that processes the Dockerfile.

Parser directives must be placed at the very top of the file. If a blank line, a regular comment, or a build instruction (such as FROM) appears before them, they are not recognized as parser directives and are treated as ordinary comments.

Basic Dockerfile with comments.

Dockerfile

# syntax=docker/dockerfile:1.4
# Parser directive: enables BuildKit 1.4+ syntax.
# Required when using here-document syntax.

# Base image: using the slim variant of Python 3.12.
# The slim variant omits debugging tools, making it suitable for production.
FROM python:3.12-slim

# Set metadata.
LABEL maintainer="team@example.com"
LABEL description="Sample Python application"

# Set the working directory.
WORKDIR /app

# Copy and install dependencies first.
# Copying only requirements.txt first allows the pip install layer
# to be cached even when the application source code changes.
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy the application source code.
COPY . .

# Declare the port the application uses (actual port publishing is done with docker run -p).
EXPOSE 8000

# Default command executed when the container starts.
CMD ["python", "main.py"]

Dockerfile (multi-stage build example)

# Example of a multi-stage build.
# Separating the build image from the runtime image keeps the final image small.

# ---- Build stage ----
# golang:1.22 is a large image that includes the full toolchain.
# It is used only for compilation and is not included in the final image.
FROM golang:1.22 AS builder

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download

COPY . .
# Disable CGO to produce a statically linked binary.
# Required to run on the distroless image.
RUN CGO_ENABLED=0 go build -o server .

# ---- Runtime stage ----
# distroless is a minimal image that does not even include a shell.
# Used to minimize the attack surface.
FROM gcr.io/distroless/static-debian12

WORKDIR /app
# Copy only the binary produced in the build stage.
COPY --from=builder /app/server .

EXPOSE 8080
CMD ["/app/server"]

Writing inline comments after a RUN instruction

Inline comments are not supported in Dockerfile. Writing RUN command # comment passes # comment to the shell as part of the command. Some shells silently ignore the # and everything after it, but the behavior is not guaranteed and can cause unexpected results. Always place comments on the line before the instruction.

# NG: inline comment — # onward is passed as part of the command
RUN apt-get update # update package list

# OK: place the comment on the line before the instruction
# Update the package list and install curl.
RUN apt-get update && apt-get install -y curl

Placing parser directives after other content

Parser directives must be placed at the very top of the file. If a blank line, a regular comment, or a build instruction (such as FROM) appears first, any # syntax= etc. written afterward is not recognized as a parser directive and is treated as an ordinary comment.

# NG: a parser directive written after FROM is ignored.
FROM ubuntu:22.04
# syntax=docker/dockerfile:1.4   ← invalid here (treated as a regular comment)

# OK: place it at the very top of the file.
# syntax=docker/dockerfile:1.4
FROM ubuntu:22.04

The only comment syntax available in a Dockerfile is #. A line beginning with # is treated as a comment. Unlike many other languages, Dockerfile does not support inline comments (writing a comment after code on the same line). Writing # comment at the end of a RUN instruction passes that text to the shell as part of the command. Comments must always be placed on the line before the instruction they describe.

# syntax= and # escape= at the very top of a Dockerfile use the same syntax as comments but are parser directives — special instructions interpreted by Docker BuildKit before parsing the rest of the file. They change the syntax version or the escape character. If a blank line or build instruction appears before them, they are no longer recognized as parser directives, so they must be placed at the very beginning of the file.