Compare Python YAML libraries¶

Choose yamluna when your Python code reads and writes YAML and you want the file, and your objects, back as they were. If you only read values and never write the file back, a library that discards formatting will be faster.

At a glance¶

Features¶

Checked with yamluna 0.1.0, ruamel.yaml 0.19.1, PyYAML 6.0.3, py-yaml12 0.2.0, and StrictYAML 1.7.3.

See the difference¶

Remove a setting, and the comment explaining it should leave too:

from yamluna import YAML

source = """image: app:1.4  # approved release
# staging only
debug: true
replicas: 3
"""

yaml = YAML()
config = yaml.load(source)
del config['debug']
print(yaml.dump(config), end='')

yamluna output:

image: app:1.4  # approved release
replicas: 3

ruamel.yaml's default YAML() and StrictYAML both leave the staging comment behind, above replicas:

import io
from ruamel.yaml import YAML

yaml = YAML()
config = yaml.load(source)
del config['debug']
output = io.StringIO()
yaml.dump(config, output)
print(output.getvalue(), end='')

image: app:1.4  # approved release
# staging only
replicas: 3

PyYAML and py-yaml12 discard both comments, including the one on the surviving image setting:

import yaml

config = yaml.safe_load(source)
del config['debug']
print(yaml.safe_dump(config, sort_keys=False), end='')

image: app:1.4
replicas: 3

How much of the file survives?¶

The project's round-trip corpus has 40 files covering comments, quoting, anchors, document markers, and different layouts. Each file is loaded and saved without edits, then compared byte for byte.

yamluna and ruamel.yaml use YAML() with preserve_quotes = True. PyYAML uses safe_load_all and safe_dump_all with sort_keys=False, and StrictYAML its round-trip dirty_load(...).as_yaml(), which rejects the files that use tags, anchors, or several documents. A separate duplicate-key file is excluded because a Python dictionary cannot hold both entries. These results describe this corpus, not every YAML file.

Speed¶

Each figure is one complete load and save of a generated input, in milliseconds; lower is faster.

Among the libraries that keep comments, yamluna is 1.7 to 6.0 times faster than ruamel.yaml and faster than StrictYAML on every input. It is also faster than pure-Python PyYAML except on the deeply nested document. PyYAML with libyaml and py-yaml12 are faster still, because they build plain dictionaries and lists and write new text rather than keeping the original's. If you never save the file back, or don't mind it being reformatted, one of those is the quicker choice.

Measured on Linux (WSL2), CPython 3.13.11, and an Intel Core i5-13400F, with the settings described above. Results depend on your files and machine. bench/libraries.py reproduces both tables and reports the median of five batches.

Before switching¶

yamluna is alpha and requires Python 3.11+. Read the short limitations page, then follow the migration guide for the library you use now, or the installation guide.