How do I add comments in YAML?

Dark navy cover card with the title 'How do I add comments in YAML?' in white and a green accent bar

To add YAML comments, type # and write your note: everything from the # to the end of the line is ignored by the parser. A comment can sit on its own line or after a value, but an inline # needs a space before it. YAML has no block comment syntax, so for several lines you put # at the start of each one.

Single-line and inline YAML comments

A YAML comment is marked by the # character and ends at the line break. The YAML 1.2.2 specification defines only this one kind of comment, in section 6.6.

Both placements look like this:

# Database settings for local development
database:
  host: localhost   # change this in production
  port: 5432
  # user: admin     (commented out, not loaded)

Comment lines are independent of the indentation level, per the spec, so the indented # user: admin above doesn't break the mapping.

The space-before-# rule

YAML comments must be separated from other tokens by white space. That one rule from the spec explains most "why did my value disappear?" bugs, because it decides whether a # starts a comment or is part of your data.

I ran a few lines through js-yaml's load() to show the effect:

YAML line Parsed value Why
color: #ff0000 null # starts a comment, so the value is empty
color: "#ff0000" "#ff0000" Inside quotes, # is text
url: http://x.dev/#frag "http://x.dev/#frag" No space before #
pass: abc#123 "abc#123" No space before #

Hex colors in theme files and CI configs hit this most. Quote any value that starts with #. Quoting is also the safe habit for passwords and tokens, which can contain # by chance.

How to comment out multiple lines

YAML has no /* ... */ style block comment. To comment out a block, put # at the start of every line, as the multi-line comment guide recommends:

# services:
#   cache:
#     image: redis
#     restart: always

You don't have to type each #. Most editors toggle comments on a selection with Ctrl+/ (Cmd+/ on macOS), and they keep the indentation, so uncommenting later restores valid YAML.

Some guides suggest a block scalar as a fake block comment:

_note: |
  This explains the settings below.

Avoid it. That text is a real key with a real value, so your application loads it. A strict schema may reject the unknown key.

Where # is not a comment

A # inside a block scalar or a quoted string is text, not a comment. In my test, this line came through as part of the value:

note: |
  # not a comment
  line

The parsed value was "# not a comment\nline\n". The same goes for # inside "double" or 'single' quotes. If you write long text blocks this way, the guide to YAML multiline strings covers how | and > treat line breaks.

One edge case from the spec: a comment can follow a block scalar header (note: | # explanation), but extra comment lines can't follow it there, because the next lines are the scalar's content.

Why tools delete your YAML comments

Most YAML libraries drop comments when they rewrite a file. The spec calls comments a presentation detail that must not be used to convey content information, and it forbids building the loaded data from them. So a normal load gives you plain objects with no comments attached, and dumping that data writes a file with none.

In my test, js-yaml's dump() after load() lost both # keep me and # and me. There's a js-yaml feature request asking for an option to keep comments from the input. If your script edits YAML and people rely on the comments, pick a library built to keep them:

  • Python: ruamel.yaml supports round-trip preservation of comments.
  • JavaScript: the yaml package parses into a Document with commentBefore and comment fields and writes them back when you stringify it.

My take: if a config file is edited by both people and scripts, use a comment-preserving library from the start. Swapping it in after someone's careful notes vanish in a bot commit is the usual way teams learn this.

Comments are also lost on any conversion to JSON, because JSON has no comments at all. That's a real limitation of browser converters too: the YAML to JSON tool on this site parses with js-yaml, so the JSON it produces carries only the data. For the bigger trade-off, see JSON vs YAML for config files.

Common mistakes with YAML comments

  1. No space before an inline #. port: 5432#main makes the value the string 5432#main, not a number with a comment.
  2. Unquoted values starting with #. Colors, channel names and some passwords turn into null.
  3. Tabs before a comment line. YAML forbids tabs for indentation; see why YAML rejects tabs.
  4. Expecting comments to survive a rewrite. Formatters, sorters and converters built on plain load/dump remove them.

FAQ

Does YAML have block or multi-line comments?

No. YAML only has the # comment, which ends at the line break. To comment out several lines, put # at the start of each one. Most editors do this for a whole selection with a toggle-comment shortcut.

Why did my value turn into null after a #?

An unquoted # with a space before it starts a comment, so everything after it is dropped. In color: #ff0000 the value is empty, which parses as null. Quote it: color: "#ff0000".

Can I put a # inside a YAML value?

Yes, if there's no space before it or the value is quoted. abc#123 and a URL with a #fragment stay intact. Inside quotes or a block scalar, # is always plain text.

Why are my comments gone after a tool rewrote the file?

Most YAML libraries load the file into plain data and write it back from that data, and comments aren't part of the data. Use a library that keeps them, such as ruamel.yaml in Python or the yaml package in JavaScript.

Sources