PyYAML

Common errors

Warnings

Install

Install compatibility verified last tested: 2026-05-12

Imports

• yaml
  wrong

  import pyyaml

  correct

  import yaml

  The PyPI slug is 'pyyaml' but the Python package name is 'yaml'. Importing 'pyyaml' raises ModuleNotFoundError.

• yaml.safe_load
  wrong

  yaml.load(stream)

  correct

  import yaml
  data = yaml.safe_load(stream)

  yaml.load() without a Loader raises TypeError in 6.0+; even with Loader=yaml.FullLoader it was vulnerable to RCE before 5.4. Always prefer safe_load() for untrusted input.

• yaml.safe_dump

  import yaml
  text = yaml.safe_dump(data, allow_unicode=True)

  safe_dump() does not accept a Dumper kwarg; use yaml.dump(data, Dumper=yaml.SafeDumper) if you need to pass one explicitly.

• yaml.YAMLError

  from yaml import YAMLError

  Base exception for all PyYAML parse and emit errors; catch this rather than bare Exception for YAML-specific error handling.

• yaml.safe_load_all

  import yaml
  for doc in yaml.safe_load_all(stream): ...

  Returns a generator; the file/stream must remain open for the entire iteration. Consuming outside the 'with' block silently returns no documents.

Quickstart verified last tested: 2026-04-23

Round-trip: parse a YAML config string then dump it back to YAML text, with safe loader/dumper throughout.

import yaml

# --- Parse YAML (safe, no arbitrary code execution) ---
raw = """
service:
  host: localhost
  port: 8080
  debug: false
tags:
  - web
  - api
"""

config = yaml.safe_load(raw)
print(config['service']['host'])   # 'localhost'
print(config['service']['port'])   # 8080  (int, not str)
print(type(config['service']['debug']))  # <class 'bool'>

# --- Dump back to YAML text ---
output = yaml.safe_dump(config, allow_unicode=True, sort_keys=False)
print(output)

# --- Load multiple documents ---
multi = """
---
name: alpha
---
name: beta
"""
import io
docs = list(yaml.safe_load_all(io.StringIO(multi)))
print(docs)  # [{'name': 'alpha'}, {'name': 'beta'}]

# --- Error handling ---
try:
    yaml.safe_load("key: [unclosed")
except yaml.YAMLError as exc:
    print(f"Parse error: {exc}")