YAML Multiline Strings in Ansible: Literal, Folded & Block Scalars
By Luca Berton · Published 2024-01-01 · Category: installation
Complete guide to YAML multiline strings in Ansible playbooks. Understand literal block (|), folded block (>), strip, keep, and indent indicators with practical examples for shell commands, templates, and configurations.
Multiline strings in YAML are controlled by block scalars — the pipe (|) and greater-than (>) characters. Getting them right is essential for shell commands, configuration templates, and clean Ansible playbooks.
Quick Reference
| Syntax | Name | Newlines | Trailing | Example Use | |--------|------|----------|----------|-------------| | | | Literal | Preserved | One \n | Shell scripts, configs | | |+ | Literal Keep | Preserved | All trailing | Scripts needing blank lines at end | | |- | Literal Strip | Preserved | None | Strings that must not end with \n | | > | Folded | Joined to spaces | One \n | Long sentences, descriptions | | >+ | Folded Keep | Joined to spaces | All trailing | Paragraphs | | >- | Folded Strip | Joined to spaces | None | Clean single-line output |
Literal Block Scalar ( | )
Preserves newlines exactly as written. Each line break in YAML becomes a \n in the string.
The resulting string:
Common Use Cases for |
Folded Block Scalar ( > )
Joins lines with spaces — newlines become spaces, creating a single long line. Empty lines create actual line breaks.
Result: This is a very long message that spans multiple lines in the YAML file but will be joined into one line.\n
Paragraphs with >
Empty lines in folded blocks create real line breaks:
Result:
Common Use Cases for >
Chomping Indicators: Strip (-) and Keep (+)
Control trailing newlines:
Default (clip) — One trailing newline
Strip (-) — No trailing newlines
Keep (+) — All trailing newlines preserved
Practical Ansible Examples
Shell Scripts (use |)
Jinja2 Templates (use |)
Long Variable Values (use >-)
Result: https://api.example.com/v2 /organizations/123/projects/456/deployments
> ⚠️ Note: Folded blocks add a space where each line break was. For URLs, you typically want the lines to join without spaces. Use plain string concatenation with Jinja2 instead:
when Conditions (use >- or >)
Multiline Variables
Common Mistakes
Using > When You Need |
Forgetting Indentation
FAQ
What is the difference between | and > in YAML?
| (literal) preserves all newlines — each line break in YAML becomes a \n in the string. > (folded) joins consecutive lines with spaces, turning multiple lines into one long line. Use | for scripts and configs; use > for long sentences.
How do I remove the trailing newline from a YAML block?
Add the strip indicator: |- or >-. This removes all trailing newlines from the block scalar value. Without it, YAML adds one trailing \n by default.
Which should I use for Ansible shell commands?
Use | (literal block) for multi-line shell scripts so each command stays on its own line. Use > (folded) for single commands with many arguments that you want on one line.
How does indentation work in YAML block scalars?
Content must be indented more than the block indicator line. The first content line sets the indentation level — all subsequent lines must match. Extra indentation within the block is preserved relative to the first line.
Can I use Jinja2 variables inside YAML multiline strings?
Yes, Jinja2 templates work inside both | and > blocks in Ansible. Variables like {{ var }} and control structures like {% if %} are processed normally.
Conclusion • | (literal) — Use for shell scripts, configs, certificates (preserves newlines) • > (folded) — Use for long descriptions, single commands with many args (joins lines) • - (strip) — Remove trailing newlines when they'd cause issues • + (keep) — Preserve all trailing newlines • Most common in Ansible: | for shell/copy content, >- for long when conditions
Related Articles • Ansible Playbook Structure & Best Practices • Ansible Playbook Examples: Complete Guide • Ansible Jinja2 Filters for Data Transformation
Category: installation