YAML Block Comments Are Not a Thing — And How to Fake Them

Q: Does YAML support block comments?

No, the YAML specification (versions 1.1 and 1.2) defines only single-line comments using the `#` character — everything from `#` to the end of the line is a comment. There is no `/* */` syntax, no multi-line comment token, and no official block comment mechanism. Any tool or library that claims to support YAML block comments is implementing a non-standard extension that will not work with standard YAML parsers.

Q: How do you comment out multiple lines in YAML?

The only standard way is to prefix each line with `#`. Most code editors support selecting multiple lines and pressing `Ctrl+/` (or equivalent) to toggle the `#` prefix on every selected line simultaneously. For structured data blocks, you can also use YAML anchors: define the block as an anchor and simply stop referencing it to "disable" the configuration. For CI/CD pipelines, some teams use preprocessor scripts that strip lines between custom `# >>BLOCK` and `# <<BLOCK` markers before the YAML parser reads the file. Yes — select the lines you want to comment out and press `Ctrl+/` (Windows/Linux) or `Cmd+/` (macOS). This adds `#` to the beginning of each selected line. Pressing the same shortcut again removes the `#` prefix. This is your fastest option for toggling blocks. VS Code also supports multi-cursor editing where you can add cursors to multiple lines and type `#` simultaneously.

Q: Why was block comment syntax never added to YAML?

The YAML specification committee has consistently prioritized parser simplicity over developer convenience features. Because YAML is whitespace-sensitive, a `/* */` block comment would create ambiguous boundary conditions — a closing `*/` inside a quoted string, inside an indented block, or split across folded lines would require contextual parsing that YAML deliberately avoids. Additionally, the YAML ecosystem has largely solved this via editor tooling, so the specification has not felt pressure to change. This frustrates many developers but is unlikely to change in future YAML versions.

Q: Can I use `---` to create block comments in YAML?

No. The `---` triple-dash separator is a document boundary marker in YAML, not a comment. It starts a new YAML document within the same file. Content after `---` is parsed as a separate document, which will likely break your configuration. Some developers mistakenly believe `---` acts as a comment delimiter because it visually separates sections, but it is a structural directive that changes how the YAML parser interprets the file. --- YAML's lack of block comments is annoying, but it forces a useful discipline: **if a section is large enough that you want to comment it out, it should probably be a separate file or a reusable anchor.** The workarounds in this guide handle most real-world scenarios. But if you find yourself fighting YAML's comment limitations constantly, consider whether your configuration files have grown too large. Modular, well-structured YAML rarely needs massive comment blocks. And when you are refactoring or debugging a YAML file with commented-out sections, paste it into a [YAML formatter](/yaml-formatter) to ensure the remaining active configuration is valid. Uncommented blocks sometimes introduce indentation inconsistencies that only surface in production.

Here is something that surprises every developer who moves from JSON, JavaScript, or C-style languages into YAML-heavy infrastructure work:

YAML has no block comment syntax.

There is no /* ... */. There is no multi-line comment. There is no official way to comment out 20 lines of a Kubernetes manifest without putting # at the start of every single line.

This is not an oversight. The YAML specification simply never defined a block comment syntax, and decades later, the ecosystem has not added one.

For developers managing large CI/CD pipelines, Helm charts, or Ansible playbooks, this limitation becomes genuinely painful. When you need to temporarily disable a block of configuration, or document a complex section inline, you either accept the tedium of line-by-line commenting or find a workaround.

This guide covers every practical approach developers use to fake block comments in YAML.

Why YAML Has No Block Comments

The YAML specification (1.1 and 1.2) defines only one comment mechanism: the # character. Everything from # to the end of the line is a comment. That is it.

The spec never proposed a block comment syntax. Every attempt to add one has been rejected by the YAML design committee, largely because:

YAML is whitespace-sensitive, making /* */ boundaries ambiguous
The spec prioritizes simplicity at the parser level
Most use cases were considered "developer tooling, not YAML's problem"

This leaves real-world developers with a gap that every YAML-heavy project eventually has to solve.

The Problem: Why Line-by-Line `#` Is Painful

Commenting out 50 lines of a Kubernetes Deployment spec:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
      - name: api
        image: api:latest
        # ports:
        # - containerPort: 8080
        # env:
        # - name: DB_HOST
        #   value: prod-db.example.com
        # - name: DB_PORT
        #   value: "5432"
        # resources:
        #   limits:
        #     memory: 512Mi
        #     cpu: 500m

Every editor that supports Ctrl+/ will handle this for you. But the problem is not the keystrokes — it is that commented-out YAML becomes visually noisy and hard to maintain.

If you accidentally leave a # in the wrong place, or miss uncommenting one line, your deployment breaks with a confusing parser error.

Workaround 1: YAML Anchors and Aliases

This is the most elegant workaround and the closest YAML has to native block toggling.

Define a block of config as an anchor, then reference it with an alias. To "comment out" the entire block, simply stop referencing it.

x-production-db: &production-db
  host: prod-db.example.com
  port: 5432
  username: deploy
  password_file: /secrets/db-password

x-staging-db: &staging-db
  host: staging-db.example.com
  port: 5432
  username: deploy
  password_file: /secrets/db-password-staging

services:
  api:
    image: api:latest
    environment:
      <<: *production-db
    # To disable production DB, swap the alias:
    # <<: *staging-db

This technique works because YAML ignores keys starting with x- or any "unused" anchor. The anchor definitions sit unused until referenced.

The downside: anchored blocks cannot contain every type of YAML construct (some parsers choke on deeply nested anchors), and the workaround only applies to data structures, not arbitrary lines.

For a full guide on anchors and aliases, see YAML Anchors and Aliases — Reduce Repeat in Your Configs. Also check Why Your YAML Is Invalid for common parsing issues that affect commented-out blocks, and How to Fix YAML Indentation Errors for debugging whitespace problems that arise when uncommenting sections.

Workaround 2: Top-Level Ignored Keys

YAML parsers ignore keys they do not recognize. You can use this to "comment out" entire sections by prepending a prefix like _ or x-.

# Active
database:
  host: prod-db

# Commented out (parser ignores unknown top-level key)
x-disabled-database:
  host: old-db
  port: 5432

This works well for structured blocks but only at the top level. Nested blocks still require # prefixes.

Workaround 3: Preprocessor with `sed` or `awk`

For CI/CD pipelines, many teams use a preprocessor step that strips or toggles comment blocks before the YAML parser sees the file.

Define custom comment markers:

# >>BLOCK_COMMENT
resources:
  limits:
    memory: 1Gi
    cpu: 1000m
# <<BLOCK_COMMENT

Then strip them in CI:

sed -i '/^# >>BLOCK_COMMENT/,/^# <<BLOCK_COMMENT/d' config.yaml

Or toggle them by replacing markers:

# Uncomment a block
sed -i 's/^# //' config.yaml

This is fragile and regex-based, but it works. Many Helm chart teams use variations of this pattern in their deployment scripts.

Workaround 4: Editor Multi-Cursor and Macros

VS Code, IntelliJ, and Neovim all support multi-cursor editing that makes line-by-line commenting tolerable.

VS Code:

Select the lines
Ctrl+/ to toggle # on each line

Vim/Neovim:

:5,20s/^/#

IntelliJ:

Ctrl+Shift+/ (varies by keymap)

This is not a true block comment, but combined with editor macros, it is fast enough for most workflows.

Workaround 5: Separate Files and `!reference`

Some YAML-based tools support file inclusion:

# docker-compose.yml
services:
  api:
    extends:
      file: api-base.yml
      service: api-base

If you want to disable a section, swap the included file:

services:
  api:
    extends:
      file: api-disabled.yml
      service: api-base

Docker Compose's extends field is one example. Ansible's include_tasks is another. CI/CD platforms like GitHub Actions support uses and workflow_call for modular workflows.

By extracting large blocks into separate files, you "comment out" configurations by changing file references rather than editing line by line.

Workaround 6: YAML Merge Fields (`<<:`)

Combine with anchors to create optional override blocks:

defaults: &defaults
  replicas: 3
  image: nginx:latest

# Disabled override — uncomment the key below to activate
# overrides: &overrides
#   replicas: 5
#   resources:
#     limits:
#       memory: 1Gi

web:
  <<: *defaults
  # <<: *overrides

When you want to disable the override, comment out the merge key. The << merge key itself accepts # comments on the same line, but the alias reference does not, so the line-level # is unavoidable.

Workaround 7: JSON Reference Files

If block commenting is a persistent pain point, consider whether parts of your config should be JSON instead of YAML.

Kubernetes accepts both. Docker Compose supports JSON. Most platforms that parse YAML also parse JSON.

# kubernetes/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  template:
    spec:
      containers:
      - name: api
        image: nginx

If commenting is constant, externalize the data-heavy sections:

# reference a JSON file where block comments are actually supported
containers:
  - name: api
    envFrom:
      - configMapRef:
          name: api-config

JSON supports /* */ block comments if you use a JSON5 parser. Some Kubernetes tools support JSON5 natively.

What Most Teams Actually Do

In practice, most YAML-heavy teams settle on a combination of:

Anchor-based toggling for structured blocks
Edit-level # toggling via Ctrl+/ for quick in-editor work
Preprocessor scripts for CI/CD block toggling
Short blocks only — if a section needs commenting, they refactor it to be smaller

The anchor approach is closest to a "real" block comment, which is why it is the most recommended workaround in the YAML community.

If you are maintaining large YAML files and struggling with block commenting, your real problem may be file size. Extract reusable parts into separate files and use !reference, extends, or include mechanisms to compose them. This makes configuration more modular and eliminates the need for massive comment blocks.

FAQ

Does YAML support block comments?

No, the YAML specification (versions 1.1 and 1.2) defines only single-line comments using the # character — everything from # to the end of the line is a comment. There is no /* */ syntax, no multi-line comment token, and no official block comment mechanism. Any tool or library that claims to support YAML block comments is implementing a non-standard extension that will not work with standard YAML parsers.

How do you comment out multiple lines in YAML?

The only standard way is to prefix each line with #. Most code editors support selecting multiple lines and pressing Ctrl+/ (or equivalent) to toggle the # prefix on every selected line simultaneously. For structured data blocks, you can also use YAML anchors: define the block as an anchor and simply stop referencing it to "disable" the configuration. For CI/CD pipelines, some teams use preprocessor scripts that strip lines between custom # >>BLOCK and # <<BLOCK markers before the YAML parser reads the file.

Is there a YAML multi-line comment shortcut in VS Code?

Yes — select the lines you want to comment out and press Ctrl+/ (Windows/Linux) or Cmd+/ (macOS). This adds # to the beginning of each selected line. Pressing the same shortcut again removes the # prefix. This is your fastest option for toggling blocks. VS Code also supports multi-cursor editing where you can add cursors to multiple lines and type # simultaneously.

Why was block comment syntax never added to YAML?

The YAML specification committee has consistently prioritized parser simplicity over developer convenience features. Because YAML is whitespace-sensitive, a /* */ block comment would create ambiguous boundary conditions — a closing */ inside a quoted string, inside an indented block, or split across folded lines would require contextual parsing that YAML deliberately avoids. Additionally, the YAML ecosystem has largely solved this via editor tooling, so the specification has not felt pressure to change. This frustrates many developers but is unlikely to change in future YAML versions.

Can I use `---` to create block comments in YAML?

No. The --- triple-dash separator is a document boundary marker in YAML, not a comment. It starts a new YAML document within the same file. Content after --- is parsed as a separate document, which will likely break your configuration. Some developers mistakenly believe --- acts as a comment delimiter because it visually separates sections, but it is a structural directive that changes how the YAML parser interprets the file.

Final Thoughts

YAML's lack of block comments is annoying, but it forces a useful discipline: if a section is large enough that you want to comment it out, it should probably be a separate file or a reusable anchor.

The workarounds in this guide handle most real-world scenarios. But if you find yourself fighting YAML's comment limitations constantly, consider whether your configuration files have grown too large. Modular, well-structured YAML rarely needs massive comment blocks.

And when you are refactoring or debugging a YAML file with commented-out sections, paste it into a YAML formatter to ensure the remaining active configuration is valid. Uncommented blocks sometimes introduce indentation inconsistencies that only surface in production.