YAML in Python: A Practical Guide

Installing PyYAML

The Python YAML library lives on PyPI as pyyaml but imports as yaml — a naming mismatch that trips up most newcomers:

# PyYAML is the de-facto YAML library for Python
pip install pyyaml

# Verify
python -c "import yaml; print(yaml.__version__)"

If import yaml fails after install, see our No module named 'yaml' troubleshooting guide.

Reading a YAML file

import yaml

with open("config.yaml", "r") as f:
    config = yaml.safe_load(f)

print(config["database"]["host"])

The return value of yaml.safe_load is a regular Python data structure — typically a dict at the top level, but could be a list or scalar depending on the YAML.

Parsing a YAML string

safe_load accepts both file objects and strings:

import yaml

raw = """
name: my-app
version: 1.4.2
features:
  - search
  - billing
"""

data = yaml.safe_load(raw)
print(data["features"])  # ['search', 'billing']

safe_load vs load vs full_load

PyYAML offers multiple loaders. They differ only in which Python objects they will construct from YAML tags:

import yaml

# SAFE - rejects arbitrary Python objects, recommended default
data = yaml.safe_load(stream)

# UNSAFE - can construct arbitrary Python objects, only use on trusted input
data = yaml.full_load(stream)   # equivalent to yaml.load(stream, Loader=yaml.FullLoader)
data = yaml.load(stream, Loader=yaml.UnsafeLoader)  # never use on untrusted YAML

Rule of thumb: always use safe_load unless you have a specific reason and the YAML source is fully trusted. yaml.load with the default loader can execute arbitrary Python via crafted YAML tags — a known CVE vector.

Writing YAML from Python

import yaml

config = {
    "name": "my-app",
    "version": "1.4.2",
    "features": ["search", "analytics"],
    "database": {"host": "db.example.com", "port": 5432},
}

# Pretty-printed YAML
print(yaml.safe_dump(config, sort_keys=False, default_flow_style=False))

Pass default_flow_style=False for human-readable block style and sort_keys=False to preserve insertion order (PyYAML alphabetizes by default).

Multiple documents in one file

Kubernetes manifests and Compose-style files often pack multiple YAML documents in a single file separated by ---. Use safe_load_all:

import yaml

# YAML files can contain multiple documents separated by ---
documents = """
---
kind: Deployment
metadata:
  name: api
---
kind: Service
metadata:
  name: api
"""

for doc in yaml.safe_load_all(documents):
    print(doc["kind"], doc["metadata"]["name"])

ruamel.yaml: round-tripping with comments

PyYAML drops comments and reorders keys on round-trip. If you need to load, edit, and save a file while preserving its formatting and comments, switch to ruamel.yaml:

# ruamel.yaml preserves comments and round-trips cleanly
pip install ruamel.yaml

# In Python:
from ruamel.yaml import YAML

yaml = YAML()           # round-trip mode by default
with open("config.yaml") as f:
    data = yaml.load(f)

# Mutate in place
data["replicas"] = 5

with open("config.yaml", "w") as f:
    yaml.dump(data, f)
# Comments survive!

Handling YAML errors with line numbers

When YAML fails to parse, the exception carries a problem_mark with line and column info:

import yaml

try:
    data = yaml.safe_load(text)
except yaml.YAMLError as e:
    if hasattr(e, "problem_mark"):
        mark = e.problem_mark
        print(f"YAML error at line {mark.line + 1}, column {mark.column + 1}: {e.problem}")
    else:
        print(f"YAML error: {e}")

PyYAML vs ruamel.yaml at a glance

Best practices

• Always use safe_load on untrusted input. yaml.load with the default loader is a remote-code execution vector.
• Set sort_keys=False on dump. Default alphabetization makes diffs unstable for human-edited config.
• Pin the version in requirements.txt. PyYAML between 5.x and 6.x changed several defaults.
• Use ruamel.yaml when comments matter. Don't fight PyYAML on round-trips — it will lose comments every time.
• Validate before deploy. Drop generated YAML into our YAML validator to catch issues before kubectl or docker compose runs.

Related YAML guides

• Fix: ModuleNotFoundError: No module named 'yaml'
• YAML syntax reference
• YAML anchors and aliases — important when parsing Compose-style YAML in Python.
• YAML validator — sanity-check files before Python parses them.