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
commentBeforeandcommentfields 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
- No space before an inline
#.port: 5432#mainmakes the value the string5432#main, not a number with a comment. - Unquoted values starting with
#. Colors, channel names and some passwords turn intonull. - Tabs before a comment line. YAML forbids tabs for indentation; see why YAML rejects tabs.
- 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.