Adding a Comment in a Dockerfile

1. Overview

In this tutorial, we’ll learn how to add comments in a Dockerfile. We’ll also highlight a distinction between instructions that look like comments but aren’t.

2. Adding a Comment to a Dockerfile

We’ll use the following Dockerfile:

FROM ubuntu:latest
RUN echo 'This is a Baeldung tutorial'

Let’s understand it quickly:

• the first line states that we use the latest ubuntu image
• the second line passes the echo command as a parameter of the shell

Let’s build our image:

$ docker build -t baeldungimage .
#4 [1/2] FROM docker.io/library/ubuntu:latest
#5 [2/2] RUN echo 'This is a Baeldung tutorial'

Docker prints (amongst other lines we’re not listing) the two steps that run successfully. Let’s now see how we can add comments to our Dockerfile.

2.1. Creating a Single-Line Comment

To comment a line, it must start with a #.

Let’s see how to modify our Dockerfile to add some single-line comments:

# Declare parent image
FROM ubuntu:latest
# Print sentence
RUN echo 'This is a Baeldung tutorial'

Let’s build the modified image:

$ docker build -t baeldungimage .
#4 [1/2] FROM docker.io/library/ubuntu:latest
#5 [2/2] RUN echo 'This is a Baeldung tutorial'

As expected, Docker successfully ran the two same steps as before.

2.2. Multi-Line Comments

There is no dedicated syntax in Docker to write multi-line comments. Thus, the only way to write a multi-line comment is to write multiple single-line comments in a row:

# This file is a demonstration
# For a Baeldung article
FROM ubuntu:latest
RUN echo 'This is a Baeldung tutorial'

Building the image still prints the same steps as before:

$ docker build -t baeldungimage .
#4 [1/2] FROM docker.io/library/ubuntu:latest
#5 [2/2] RUN echo 'This is a Baeldung tutorial'

3. Avoiding Pitfalls

In this section, we’ll look at a couple of pitfalls we should be aware of. These are tricky lines of code that look like comments when they are not.

3.1. Comment or Command Argument?

In Docker, it’s impossible to add a comment at the end of a line. Let’s see what happens if we try to add a sentence, formatted like a single-line comment, at the end of one of our instructions:

FROM ubuntu:latest
RUN echo 'This is a Baeldung tutorial' # Print sentence

We’ll now build the image:

$ docker build -t baeldungimage .
#4 [1/2] FROM docker.io/library/ubuntu:latest
#5 [2/2] RUN echo 'This is a Baeldung tutorial' # Print sentence
#5 0.371 This is a Baeldung tutorial

We’ve included the sentence printed by the echo command to emphasize that the result’s indeed the same as what we had before. So what happened here? Did we actually add a comment at the end of the second line of our Dockerfile?

Actually, the # Print sentence is passed as additional arguments to the RUN command. In this case, the additional arguments happened to be ignored by this command. To convince ourselves, let’s now add a similar sentence at the end of the first line of our Dockerfile:

FROM ubuntu:latest # Declare parent image
RUN echo 'This is a Baeldung tutorial'

Let’s try to build this image:

$ docker build -t baeldungimage .
failed to solve with frontend dockerfile.v0: failed to create LLB definition: dockerfile parse error line 1: FROM requires either one or three arguments

Here, we got a very explicit error message which demonstrates our affirmation.

3.2. Parser Directives Are Not Comments

Parser directives tell the Dockerfile parser how to handle the content of the file. Similarly to comments, parser directives start with a #.

Additionally, we should note that parser directives must be at the top of the Dockerfile. For instance, we’ll use the escape parser directive in our file. This directive changes the escape character used in the file:

# escape=`
FROM ubuntu:latest
RUN echo 'This is a Baeldung tutorial&' `
  && echo 'Print more stuff'

Here, we’ve added another echo instruction to the RUN command. For more readability, we’ve put this instruction on a new line. The default line separator is \. However, since we used the parser directive, we need to use ` instead. Let’s now build our image and see what happens:

$ docker build -t baeldungimage .
#4 [1/2] FROM docker.io/library/ubuntu:latest
#5 [2/2] RUN echo 'This is a Baeldung tutorial&' && echo 'Print more stuff'
#5 0.334 This is a Baeldung tutorial&
#5 0.334 Print more stuff

The two sentences have been printed as expected.

4. Conclusion

In this article, we’ve seen how to write comments in a Dockerfile. We’ve also learned that there’s a set of instructions called parser directives, that look very similar to comments but have a real impact on our file.

As always, the code can be found over on GitHub.