Write comments in a Dockerfile

Write ordinary Dockerfile comments on their own lines beginning with #. An inline # is generally part of an instruction's arguments; whether another interpreter later treats it as a comment depends on that instruction.

# Install the tools needed to verify HTTPS downloads.
RUN apt-get update \
    && apt-get install -y --no-install-recommends curl ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Run the application in the foreground.
CMD ["python", "app.py"]

This is a fragment for a compatible base image containing Python and apt. Good comments explain the reason for an instruction or a constraint that would otherwise be easy to miss.

Inline text is not a general Dockerfile comment

RUN echo ready # This is interpreted by the shell.

Docker passes the shell-form command to its configured shell. A normal POSIX shell recognizes this unquoted # as a shell comment. That does not make inline comments valid for every Dockerfile instruction: appending similar text to COPY, for example, changes the arguments Docker parses and can break the build.

Inside a quoted string, # can simply be data. Prefer separate comment lines when documenting Dockerfile instructions so the result does not depend on a second parser.

Comments can appear within a continued instruction

Contrary to a common rule of thumb, full-line comments are removed before Docker executes an instruction, so this is valid:

RUN echo hello \
# Explain why the next argument is needed.
    world

The resulting command is effectively echo hello world. The backslash continues the instruction, not the comment itself. Keep continuation syntax clear and do not append trailing text after a continuation backslash. Putting explanations above the whole instruction is often easier to read, even where an intervening comment is allowed.

Parser directives are special

Place supported directives at the very top, before ordinary comments, blank lines, or instructions:

# syntax=docker/dockerfile:1

This selects the Dockerfile frontend. The escape directive can change the escape character, which is especially relevant to Windows paths; for example, # escape= followed by a backtick selects backtick escaping. Do not add that directive to a Dockerfile whose continuations still assume backslashes without updating them.

Once the parser has moved past the directive section, a similar-looking line is treated as an ordinary comment rather than a late configuration change. Directives such as syntax, escape, and supported build-check settings are not interchangeable with prose comments.

FAQ

Do comments invalidate the build cache?

Ordinary comment-only edits do not change the executed Dockerfile instruction. However, changing a parser directive can alter parsing or frontend behavior, and copying the Dockerfile itself through COPY . . makes its changed file contents a build input.

Are block comments supported?

There is no general block-comment delimiter. Prefix each ordinary comment line with #.

What about .dockerignore?

Its comment rules are separate: Docker documents lines beginning with # in column one as comments. Do not assume every Dockerfile whitespace or continuation rule applies to ignore patterns.

See the Dockerfile format and directive reference and build-context ignore rules.