Master PyYAML: Safe Loading, Order Preservation, and Advanced Tips

Always Use safe_load / safe_dump

PyYAML's load can construct arbitrary Python objects, potentially executing any code, so you should always use yaml.safe_load and yaml.safe_dump to keep your application safe.

Preserve Field Order

Since Python 3.7+, dict preserves insertion order, so yaml.safe_load returns a dict whose keys keep the original file order. When dumping, pass sort_keys=False to yaml.safe_dump to retain that order.

>> import yaml
>>> text = """---
... c: 1
... b: 1
... d: 1
... a: 1
... """
>>> d = yaml.safe_load(text)
>>> d
{'c': 1, 'b': 1, 'd': 1, 'a': 1}
>>> list(d)
['c', 'b', 'd', 'a']

Dumping while keeping order:

>> print(yaml.safe_dump(d))
a: 1
b: 1
c: 1
d: 1
>>> d['e'] = 1
>>> print(yaml.safe_dump(d, sort_keys=False))
c: 1
b: 1
d: 1
a: 1
e: 1

If you need compatibility with older Python versions, you can replace yaml with the oyaml library.

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

Optimize List Indentation

By default PyYAML aligns list items with their parent, which many style guides (e.g., Ansible, HomeAssistant) consider suboptimal. Define an IndentDumper class to increase indentation.

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

Use it when dumping:

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

Note: yaml.safe_dump has its own Dumper class; passing a custom Dumper to it may cause conflicts.

Output Readable UTF‑8 Characters

PyYAML escapes non‑ASCII characters by default. Pass allow_unicode=True to yaml.safe_dump to output actual UTF‑8 characters.

>> d = {'a': '你好'}
>>> print(yaml.safe_dump(d))
a: "\u4F60\u597D"
>>> print(yaml.safe_dump(d, allow_unicode=True))
a: 你好

Some YAML‑Related Libraries

oyaml

oyaml

is a drop‑in replacement for the yaml package that preserves dict key order during dump/load. It is a single‑file library (~53 lines) that can be copied directly into a project.

strictyaml

StrictYAML provides a type‑safe subset of YAML, offering stronger safety guarantees for input/output when security is a concern.

ruamel.yaml

ruamel.yaml

is a maintained fork of PyYAML focused on YAML 1.2. It excels at round‑trip preservation of comments, key ordering, and formatting. Its safe_load differs slightly and cannot parse flow‑style collections such as a: {"foo": "bar"}.

Conclusion

YAML is easy to read and has a gentle learning curve, but its specification is complex, leading to inconsistencies across implementations. The tips above help avoid common pitfalls, improve safety, and make YAML handling more reliable in Python projects.