YAML Cheatsheet (.yaml / .yml)
.yaml and .yml are the same format — just two accepted file extensions. YAML (“YAML Ain’t Markup Language”) is whitespace-sensitive and a strict superset of JSON in modern parsers.
Basic Syntax Rules
- Indentation uses spaces only, never tabs.
- Indentation level defines nesting (like Python).
- Keys and values are separated by
:(colon + space — the space matters). - Comments start with
#. - Document start/end markers:
---(start),...(end) — optional for single documents.
Scalars (Strings, Numbers, Booleans, Null)
string_plain: hello world
string_single: 'single quoted string'
string_double: "double quoted string with \n escapes"
number_int: 42
number_float: 3.14
boolean_true: true # also: True, yes, on
boolean_false: false # also: False, no, off
null_value: null # also: ~, or just leave blank
empty_value:
explicit_string_number: "123" # quote to force a number to be treated as a string
Multi-line Strings
literal_block: |
This preserves
line breaks
exactly as written.
folded_block: >
This folds
line breaks
into spaces, producing one paragraph.
literal_strip: |-
No trailing newline at all.
literal_keep: |+
Keeps all trailing
blank lines.
| Indicator | Meaning |
|---|---|
\| |
Literal block — preserves newlines |
> |
Folded block — newlines become spaces |
- (suffix) |
Strip trailing newline |
+ (suffix) |
Keep trailing newlines |
Lists (Sequences)
fruits:
- apple
- banana
- cherry
# Inline flow style (JSON-like)
fruits_inline: [apple, banana, cherry]
# List of objects
people:
- name: Alice
age: 30
- name: Bob
age: 25
# Nested lists
matrix:
- [1, 2, 3]
- [4, 5, 6]
Mappings (Dictionaries)
person:
name: Alice
age: 30
address:
city: Berlin
zip: "10115"
# Inline flow style
person_inline: {name: Alice, age: 30}
Anchors, Aliases & Merge Keys (avoid repetition)
defaults: &defaults
adapter: postgres
timeout: 30
development:
<<: *defaults # merge key — inherits all defaults
database: dev_db
production:
<<: *defaults
database: prod_db
timeout: 60 # overrides the merged value
# Anchors on scalars/lists too
common_tags: &tags
- env
- team
service_a:
tags: *tags
Multiple Documents in One File
---
name: doc1
value: 1
---
name: doc2
value: 2
Type Coercion Gotchas
version: 1.0 # parsed as a FLOAT, not a string — quote it if you need "1.0" literally
country_code: NO # WARNING: parsed as boolean `false` in YAML 1.1 (Norway's code!) — quote it: "NO"
zip_code: 00501 # parsed as a string automatically since it has a leading zero (in most parsers)
enabled: yes # parsed as boolean true
port: "8080" # quote when the field must remain a string, even though it looks numeric
Rule of thumb: quote any scalar that could be misread as a number, boolean, or null — especially country codes, version-like strings, and zip codes.
Environment Variable Substitution (tool-dependent, not native YAML)
# Docker Compose style
image: myapp:${TAG:-latest}
# GitHub Actions style
env:
MY_VAR: ${{ secrets.MY_SECRET }}
# Plain YAML has NO built-in variable substitution —
# this is a feature of the specific tool consuming the YAML (Compose, Helm, CI systems, etc.)
Common Real-World Examples
GitHub Actions Workflow
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: pip install -r requirements.txt
- run: pytest
Kubernetes Manifest
apiVersion: apps/v1
kind: Deployment
metadata:
name: myapp
labels:
app: myapp
spec:
replicas: 3
selector:
matchLabels:
app: myapp
template:
metadata:
labels:
app: myapp
spec:
containers:
- name: myapp
image: myapp:latest
ports:
- containerPort: 8080
env:
- name: ENV
value: production
resources:
limits:
memory: "512Mi"
cpu: "500m"
Ansible Playbook
- name: Configure web servers
hosts: webservers
become: true
vars:
http_port: 80
tasks:
- name: Install nginx
apt:
name: nginx
state: present
- name: Start nginx
service:
name: nginx
state: started
enabled: true
Python: Reading/Writing YAML
import yaml
with open("config.yaml") as f:
data = yaml.safe_load(f) # always use safe_load, not load (security)
with open("out.yaml", "w") as f:
yaml.safe_dump(data, f, default_flow_style=False, sort_keys=False)
# Multiple documents
docs = list(yaml.safe_load_all(open("multi.yaml")))
Validating YAML
python -c "import yaml, sys; yaml.safe_load(open(sys.argv[1]))" config.yaml
yamllint config.yaml # dedicated linter, catches style + syntax issues
Common Gotchas
- Tabs are illegal for indentation — many cryptic parse errors trace back to a stray tab character.
- Trailing whitespace after
:before a value can cause unexpected parsing in some parsers — be consistent with exactly one space. on,off,yes,no,true,false(in any case) are booleans in YAML 1.1 — quote them if you want the literal string.- Colons inside unquoted string values need care:
time: 10:30can confuse a parser — quote it:time: "10:30". - Indentation must be consistent within a block — mixing 2 and 4 spaces at the same level breaks parsing.
- Duplicate keys in a mapping are often silently allowed by parsers (last one wins) rather than raising an error — a linter will catch this, plain parsing may not.