Last updated: April 28, 2026
YAML Comments: A Complete Guide
How to write single-line, inline, and multiline comments in YAML, what works in Kubernetes and GitHub Actions, and the gotchas that break otherwise valid files.
Written by Mohan Raj Kolavi.
Quick answer: How to comment in YAML
Start a line with # and everything after the hash on that line is a comment. You can also place a comment after a value on the same line, separated by whitespace. YAML has no block-comment syntax - for multiline comments, prefix every line with #.
Single-line comments
The simplest YAML comment starts a line with #. You can also tail a comment after a value on the same line:
# This is a comment name: my-app # Inline comment after a value version: 1.4.2
The parser drops everything from # to the end of the line, so comments never appear in the parsed data structure.
Multiline comments
YAML does not have a block-comment syntax. To comment a block, prefix every line with #:
# Line one of the comment # Line two of the comment # Line three of the comment name: my-app
Most editors have a "toggle comment" shortcut (Cmd+/ on macOS, Ctrl+/ on Windows / Linux) that adds or removes # on every line in the current selection.
There is no /* */ block comment
C-style block comments do not exist in YAML. The following will produce a parser error or silently treat the lines as data:
# YAML has no block comment syntax. Each line needs its own #. # /* # Not valid YAML - this would be a parse error. # */
Comments inside lists and maps
Comments can sit between list items or map keys without breaking the structure. They are useful for explaining why a particular value exists:
servers:
# The primary API server
- host: api.example.com
port: 443
# The fallback server
- host: api-backup.example.com
port: 443
The description-field trick for "permanent" comments
If you need documentation that survives a YAML to JSON conversion, put the text inside a description field as a literal block scalar (|). It travels with the data instead of being stripped:
# Trick: a description field can hold "comment-like" docs
config:
description: |
These lines are part of a literal scalar, NOT a comment.
They survive YAML to JSON conversion intact.
active: true
YAML comment rules at a glance
- Comments start with
#and run to the end of the line. - Inline comments need at least one space between the value and the
#. #inside a quoted string is a literal character, not a comment.- No block comment syntax exists - every line needs its own #.
- Comments are dropped when YAML is converted to JSON or another non-comment format.
- Document strings in description fields if you need them to persist through conversion.
Comments in Kubernetes, GitHub Actions, and Docker Compose
All three formats are standard YAML, so comments work identically. Common uses:
- Kubernetes - document why a deployment uses specific resource limits, owner team, ticket reference.
- GitHub Actions - mark a step as temporarily disabled, document the reason, link to a PR.
- Docker Compose - explain custom port mappings, volume choices, or commented-out services kept for reference.
Validate your YAML before commit
Bad indentation around a comment can break the file. Drop your YAML into our YAML validator for an instant syntax check, or use the YAML editor for live validation as you type.
Frequently Asked Questions
How do you write a comment in YAML?
Start any line with the hash character (#) and the rest of the line is treated as a comment. You can also place a comment after a value on the same line by separating it from the value with whitespace. Example: name: my-app # production app.
Does YAML support multiline comments?
YAML does not have a native block-comment syntax like /* ... */. To write a multiline comment, prefix every line you want to comment with the # character. Most editors have a 'toggle comment' shortcut that does this for a selected block.
Can I put a comment after a value in YAML?
Yes. Place at least one space after the value, then the # character and the comment text. Example: timeout: 30 # seconds. The parser drops the comment and keeps only the value.
Are comments preserved when YAML is converted to JSON?
No. JSON has no comment syntax, so comments are dropped during YAML to JSON conversion. If you need to preserve documentation, move comments into a description field or a separate readme file.
Can I comment out a YAML key?
Yes. Add a # at the start of the line containing the key. The parser will skip that key entirely. Be careful with multi-line values (block scalars and nested maps) - you must comment every line of the value as well, not just the key line.
Why is my YAML comment causing an error?
The most common cause is a missing space between the value and the # character. YAML requires whitespace before an inline comment. Another cause is a # inside a flow value where the parser treats it as part of the string - quote the value to fix this.
Do GitHub Actions YAML files support comments?
Yes. GitHub Actions reads workflow files as standard YAML, so comments work the same way. They are useful for documenting why a step exists or marking a temporary disable.
Do Kubernetes YAML manifests support comments?
Yes. kubectl ignores comments when applying manifests. They are useful for documenting non-obvious config choices, owner contacts, and ticket references.
Can YAML comments contain special characters?
Yes. Everything from the # to the end of the line is treated as comment text, including quotes, brackets, and Unicode characters. The only restriction is the line break, which always ends the comment.
Is there a way to write a multiline comment in YAML?
Not as a single token. The cleanest approximation is a block of consecutive single-line comments, each starting with #. Some teams use a description field with a literal block scalar (|) for longer documentation that should travel with the data.