PyYAML

Warnings

• breaking yaml.load() now requires an explicit Loader argument. Calling yaml.load(data) without Loader raises TypeError in 6.0+. Previously it issued a DeprecationWarning (5.1–5.4) before becoming a hard error.
  Fix: Replace yaml.load(data) with yaml.safe_load(data) for plain data, or yaml.load(data, Loader=yaml.SafeLoader) if you must use load().
• breaking yaml.load() / yaml.full_load() with FullLoader were vulnerable to arbitrary code execution (CVE-2020-14343) on untrusted input in versions before 5.4. yaml.Loader (UnsafeLoader) remains dangerous in all versions.
  Fix: Always use yaml.safe_load() or yaml.safe_load_all() for any input not fully controlled by the application. Never pass Loader=yaml.Loader (UnsafeLoader) on untrusted data.
• gotcha PyYAML implements YAML 1.1, not YAML 1.2. Values like 'yes', 'no', 'on', 'off', 'true', 'false' (all case variants) are parsed as booleans. The two-letter country code 'NO' becomes Python False. Octal literals use the 0777 syntax (not 0o777). These differ from YAML 1.2 and JSON.
  Fix: Quote string values that look like booleans or octal numbers (e.g., 'NO', '0755'). Use explicit !!str tags if quoting is not possible.
• gotcha yaml.safe_dump() escapes non-ASCII characters to \uXXXX by default, making UTF-8 content unreadable in the output file.
  Fix: Pass allow_unicode=True to yaml.safe_dump() or yaml.dump() to emit UTF-8 characters directly.
• gotcha Sexagesimal (base-60) number parsing: a YAML 1.1 value like '1:30' is parsed as the integer 90, not a string. This silently corrupts time-string fields.
  Fix: Quote time-like strings explicitly, e.g. '"1:30"', or use a YAML 1.2-compliant library such as ruamel.yaml.
• gotcha yaml.safe_load_all() returns a lazy generator. If the stream is closed before the generator is exhausted (e.g., outside a 'with' block), iteration silently yields nothing or raises an error.
  Fix: Consume the generator inside the 'with' block, or eagerly materialise it with list(yaml.safe_load_all(f)) before the block exits.
• gotcha Tabs are not valid YAML indentation. Files indented with tabs instead of spaces raise a yaml.scanner.ScannerError that can be cryptic to diagnose.
  Fix: Configure editors to expand tabs to spaces for .yaml/.yml files. Use a linter (yamllint) in CI to catch tab indentation early.

Install

• pip install pyyaml pip (pure Python + optional C extension)
• pip install pyyaml libyaml pip with explicit libyaml (faster C bindings)

Imports

• yaml

  import yaml

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

  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

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}")