Last updated: April 28, 2026
YAML Multiline Strings: Block Scalars Explained
The complete guide to YAML multiline strings: literal (|) and folded (>) block scalars, chomping indicators, quoted alternatives, and the indent gotchas that break otherwise correct files.
Written by Mohan Raj Kolavi.
Quick answer
Use | after a key to write a literal block scalar - newlines are kept as written. Use > to write a folded block scalar - newlines become spaces and the content reads like one paragraph. Add - to strip the final newline or + to keep all trailing newlines.
Literal block scalar (|)
The literal style preserves newlines exactly as you type them. It is the right choice for shell scripts, code blocks, formatted text, or anything where the line structure matters:
description: | This is line one. This is line two. This is line three.
Parsed value: "This is line one.\nThis is line two.\nThis is line three.\n"
Folded block scalar (>)
The folded style replaces single newlines with spaces. Use it for long descriptions, error messages, or any prose you want stored as a single line at runtime:
description: > This is one long paragraph that gets folded into a single line with spaces.
Parsed value: "This is one long paragraph that gets folded into a single line with spaces.\n"
Two consecutive newlines in the source become a single newline in the output, so blank lines act as paragraph breaks.
Chomping indicators: -, +, and the default
The chomping indicator controls trailing newlines:
|-or>-- strip every trailing newline.|+or>+- keep every trailing newline.|or>- keep exactly one trailing newline (the "clip" default).
description: |- No trailing newline. The hyphen strips it.
description: |+ Keep all trailing newlines.
Quoted multiline strings
For shorter strings with embedded special characters, use quoted forms instead of block scalars:
message: "Line one\nLine two\tIndented"
Double-quoted strings support C-style escape sequences: \n for newline, \t for tab, \\ for a literal backslash, and \" for a literal quote.
path: 'C:\Users\me\Documents'
Single-quoted strings treat all content as literal. The only escape is two single quotes ('') for a single quote character.
The indent indicator
You can add a numeric indent indicator after | or > to tell the parser exactly how many spaces of indentation count as the base. This is useful when your content starts with extra whitespace that needs to be preserved:
# Indent indicator (number after | or >)
script: |2
indented two extra spaces below the indentation indicator
this entire line is part of the script
Which style should you use?
- Shell scripts, code, formatted text - use
|with the default chomp. - Long prose / descriptions - use
>so the runtime gets one clean string. - Embedded newlines or tabs in short strings - use double-quoted with
\nescapes. - Strings with backslashes that should not be escaped - use single-quoted (Windows paths, regex).
- Trailing whitespace matters - pick the chomping indicator (
-or+) explicitly so behavior is obvious to the next reader.
Validate your block scalars
Indentation mistakes in block scalars are silent in many editors. Drop the file into our YAML validator to confirm it parses, or use the YAML to JSON converter to inspect exactly what the runtime will see.
Frequently Asked Questions
How do I write a multiline string in YAML?
Use a block scalar. Place a pipe (|) after the key for a literal block where newlines are preserved, or a greater-than sign (>) for a folded block where newlines become spaces. The body is indented two spaces under the key.
What is the difference between | and > in YAML?
Pipe (|) is a literal block scalar - newlines are kept exactly as written. Greater-than (>) is a folded block scalar - newlines become single spaces, making the content read like one paragraph after parsing.
How do I keep or strip trailing newlines in YAML block scalars?
Add a chomping indicator after | or >. The minus (|-) strips the final newline. The plus (|+) keeps every trailing newline. With no indicator, exactly one trailing newline is kept (the 'clip' default).
How do I write a multiline string with special characters?
Use a double-quoted string and escape sequences. Inside double quotes, \n inserts a newline, \t inserts a tab, and \\ inserts a backslash. Single-quoted strings treat all content as literal except for the quote character itself.
Why is my YAML multiline string not working?
Most often the body of the block scalar is not indented far enough or far enough consistently. Every line of the value must indent past the column of the first character after the | or > indicator. Mixing tabs with spaces also breaks YAML parsing.
How do I write JSON-style multiline strings in YAML?
Quote the string and embed \n escape sequences inside double quotes. Example: message: "Line one\nLine two". This works the same way as multiline JSON strings, since YAML 1.2 is a superset of JSON.
Can I have a multiline string in a YAML list?
Yes. The block scalar follows a list-item hyphen exactly like it follows a map key. Use - | for a literal list-item and indent the body under the hyphen.
Does YAML preserve indentation inside block scalars?
Yes, but the parser strips the leading indentation that matches the block's base indent. Add an explicit indentation indicator (a number after | or >) if your content starts with extra leading whitespace you need preserved.
How do I write a long single-line string without folding?
Wrap the string in double quotes and let it span the line in source. Or use the | block scalar without any newlines. For automatic line wrapping in your editor, leave hard-wrap off and let the parser see one logical line.
Are tabs allowed in YAML multiline strings?
YAML does not allow tabs for indentation. Inside a block scalar, tabs in the content itself are usually fine, but any line that begins with a tab is rejected by the parser. Use spaces for all leading whitespace.