YAML Comments

YAML comments start with a hash sign, #, and run to the end of the line. That is the entire syntax. But because YAML has no block comment and because # can appear inside values, there are a few rules worth knowing so your comments never break the file.

Basic comment syntax

# This is a full-line comment
name: yamlchecker   # This is an inline comment after a value
port: 8080

The parser ignores # and everything after it. Comments can appear on their own line, after a key-value pair, after a list item, or between documents in a multi-document stream.

Inline comments need a space

A # only starts a comment if it is at the beginning of the line or preceded by whitespace. Without the space it is part of the value:

color: #ff0000     # comment: the value is null, the hex code was treated as a comment
color: "#ff0000"   # correct: quoted, so the hash is part of the string
tag: v1.0#beta     # no space before #, so the value is "v1.0#beta"

The first line is the classic mistake. #ff0000 is read as a comment and color becomes null. Quote any value that begins with a hash.

Multiline comments

YAML has no block comment syntax. To comment out a paragraph or a block of configuration, prefix every line with #:

# Database settings
# These are overridden by DATABASE_URL in production.
# Do not commit real credentials here.
database:
  host: localhost
  port: 5432
  # user: admin
  # password: changeme

Indentation inside a comment does not matter to the parser, but keeping commented-out lines aligned with the surrounding keys makes it easy to uncomment them later without introducing an indentation error.

Comments in lists and nested structures

features:
  - validator      # always on
  # - formatter    # disabled until v2
  - converter

server:
  # Bind address. Use 0.0.0.0 inside containers.
  host: 127.0.0.1
  port: 8080

Comments in multiline strings

Inside a literal (|) or folded (>) block scalar, a # is plain text, not a comment:

script: |
  # This line is part of the string, not a YAML comment
  echo "hello"

This is exactly what you want when the block contains a shell script or a config file with its own comment syntax. See the guide on YAML multiline strings.

Comments and document markers

Comments are allowed before the --- document start marker and after the ... end marker, which is handy for describing each manifest in a Kubernetes file:

# Deployment for the web tier
---
apiVersion: apps/v1
kind: Deployment
# Service that exposes it
---
apiVersion: v1
kind: Service

Things that are not comments

• // and /* */ are not comments in YAML. They will be parsed as part of a value or cause a syntax error.
• A # inside single or double quotes is a literal character.
• The %YAML and %TAG lines at the top of a file are directives, not comments.

Comments are not data

Comments exist only in the text. When a program loads a YAML file and writes it back out, the comments are gone unless the library specifically round-trips them (ruamel.yaml in Python does; PyYAML and js-yaml do not). The same applies to the YAML formatter and YAML to JSON converter on this site. Keep the original file if the comments matter.