Mastering PyYAML: Safe Loading, Preserving Order, and Advanced Formatting Tricks

YAML is a widely used data serialization language, but handling YAML files with PyYAML can be painful.

Note: The code in this article works under Python 3.

Always use safe_load/safe_dump

PyYAML's load can construct arbitrary Python objects, which may execute any function; therefore always prefer yaml.safe_load and yaml.safe_dump for security.

Preserve field order

Since Python 3.7, dict preserves insertion order, so yaml.safe_load retains the original key order. Use yaml.safe_dump(..., sort_keys=False) to keep that order when dumping.

import yaml
text = """---
... c: 1
... b: 1
... d: 1
... a: 1
"""
d = yaml.safe_load(text)
print(d)  # {'c': 1, 'b': 1, 'd': 1, 'a': 1}
print(list(d))  # ['c', 'b', 'd', 'a']
print(yaml.safe_dump(d, sort_keys=False))
# c: 1
# b: 1
# d: 1
# a: 1

For older Python versions or broader compatibility, the oyaml library can be used as a drop‑in replacement to preserve order.

import oyaml as yaml
d = yaml.safe_load(text)
print(d)  # OrderedDict([...])
print(yaml.safe_dump(d, sort_keys=False))
# c: 1
# b: 1
# d: 1
# a: 1

Optimize list item indentation

By default PyYAML aligns list items with their parent, which many style guides (e.g., Ansible, HomeAssistant) consider poor. Define a custom dumper to indent list items by two spaces.

class IndentDumper(yaml.Dumper):
    def increase_indent(self, flow=False, indentless=False):
        return super(IndentDumper, self).increase_indent(flow, False)

print(yaml.dump({'a': [1, 2, 3]}, Dumper=IndentDumper))
# a:
#   - 1
#   - 2
#   - 3

Note: Passing a custom Dumper to yaml.safe_dump can cause conflicts because it uses its own dumper class.

Output readable UTF‑8 characters

PyYAML defaults to ASCII output, escaping Unicode characters. Use allow_unicode=True to emit proper UTF‑8 strings.

d = {'a': '你好'}
print(yaml.safe_dump(d, allow_unicode=True))
# a: 你好

Some YAML‑related libraries

oyaml

Link: https://github.com/wimglenn/oyaml

oyaml is a single‑file drop‑in replacement for PyYAML that preserves key order.

strictyaml

Link: https://github.com/crdoconnor/strictyaml

Provides a type‑safe subset of the YAML spec; useful when security is a priority.

ruamel.yaml

Link: https://yaml.readthedocs.io/en/latest/overview.html

A maintained fork of PyYAML focusing on YAML 1.2 and round‑trip preservation of comments, ordering, and formatting.

Note: ruamel.yaml’s safe load cannot parse flow‑style collections like a: {"foo": "bar"} , so use with care.

Conclusion

YAML is easy to read and has a gentle learning curve, but its specification is complex, leading to inconsistencies across implementations. Despite its quirks, it remains a top‑choice configuration language, and the tips above aim to make its use smoother and safer.