pyyaml

library6.0.3pypypi✓ verified 29d ago

PyYAML is a YAML 1.1 parser and emitter for Python, providing safe and unsafe loaders, a complete Unicode-aware parser, pickle-compatible serialisation, and a capable extension API for custom tags and representers. Current version is 6.0.3 (released September 2025), which adds Python 3.14 and experimental free-threading support. The 6.x line follows an irregular maintenance cadence with patch releases typically spaced 1–2 years apart; a 7.0 dev branch exists but has no published release date.

serialization

pip install pyyaml

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · PYYAML

pyyaml

serializationpythonv6.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v6.0.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

1/2 runs

py 3.11

1/2 runs

py 3.12

1/2 runs

py 3.13

1/2 runs

py 3.9

1/2 runs

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

yaml

✓ import yaml

✗ import pyyaml

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(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.

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

Debug

Known issues

breakingyaml.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().

affects: <6.0

breakingyaml.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.

affects: <5.4

gotchaPyYAML 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.

affects: all

gotchayaml.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.

affects: all

gotchaSexagesimal (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.

affects: all

gotchayaml.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.

affects: all

gotchaTabs 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.

affects: all

breakingPyYAML's C extensions, which provide significant performance, require the libyaml C library to be present during installation. If libyaml is not installed on the system, pip may fail to find a suitable wheel or compile the extensions from source, leading to installation errors such as 'ERROR: Could not find a version that satisfies the requirement libyaml' or compilation failures.

fix

Ensure the libyaml development package (e.g., 'libyaml-dev' on Debian/Ubuntu, 'libyaml-devel' on RHEL/Fedora) is installed on the system before attempting to install PyYAML via pip.

affects: all

breakingPyYAML's installation can fail if the 'libyaml' C library development packages are not available in the system environment. This is especially true when a pre-built wheel is not available for the specific Python version and OS (e.g., musllinux/Alpine), forcing a source build that requires libyaml headers. The error 'ERROR: Could not find a version that satisfies the requirement libyaml' or 'No matching distribution found for libyaml' often points to this issue.

fix

Ensure the 'libyaml' development packages are installed in the system environment. For Alpine Linux, use 'apk add libyaml-dev'. For Debian/Ubuntu, use 'apt-get install libyaml-dev'. For Fedora/RHEL, use 'yum install libyaml-devel' or 'dnf install libyaml-devel'.

affects: all

Errors

Common errors & fixes

YAMLLoadWarning: calling yaml.load() without Loader=... is deprecated

The `yaml.load()` function was called without explicitly specifying a `Loader` class, triggering a warning that the default `Loader` might be unsafe for untrusted input.

fix

Explicitly specify a loader, typically `Loader=yaml.SafeLoader` for basic safe parsing or `Loader=yaml.FullLoader` for more features, to suppress the warning and enhance security: `data = yaml.load(yaml_file_content, Loader=yaml.SafeLoader)`

ModuleNotFoundError: No module named 'yaml'

The PyYAML library is not installed in the current Python environment or the script is attempting to import 'yaml' without it being available.

fix

Install the library using pip: `pip install PyYAML`

yaml.scanner.ScannerError: while scanning a simple key

The YAML content being parsed contains a syntax error, commonly due to incorrect indentation, missing colons, or invalid characters.

fix

Review and correct the YAML syntax in the file or string, ensuring proper indentation, valid key-value structure, and adherence to the YAML specification.

yaml.representer.RepresenterError: cannot represent an object

PyYAML attempted to serialize a custom Python object (e.g., an instance of a user-defined class or certain built-in types like sets) for which it has no predefined rule (representer) on how to convert it to YAML.

fix

Define a custom representer for the specific object type using `yaml.add_representer()` to instruct PyYAML on how to serialize it, or convert the object to a standard Python type that PyYAML can handle before dumping.

Upgrade

Version history

6.0.3latest on PyPI · released Sep 25, 2025

Audit

Dependencies

libyamloptionalOptional C extension (LibYAML) that significantly speeds up parsing and emitting. PyYAML falls back to pure Python if not present.

Agent activity

21 hits · last 30 days

node

Resources

githubhttps://github.com/yaml/pyyaml ↗

packagehttps://pypi.org/project/pyyaml/ ↗

homepagehttps://pyyaml.org/ ↗

docshttps://pyyaml.org/wiki/PyYAMLDocumentation ↗