Skip to content

Easily Understand YAML with PyYAML


YAML: The Missing Battery in Python

Python is a popular programming language known for its extensive standard library. However, one area where Python lacks built-in support is with the YAML data format. YAML, which stands for “YAML Ain’t Markup Language,” is commonly used for configuration and serialization. In this tutorial, we will explore how to work with YAML in Python using the PyYAML library.

Taking a Crash Course in YAML

Before diving into Python and PyYAML, let’s have a quick crash course in YAML. YAML is a human-readable data serialization format that emphasizes simplicity and readability. It is often used for configuration files, data exchange between languages, and as an alternative to XML and JSON.

Comparison With XML and JSON

YAML has similarities to both XML and JSON but provides more simplicity and expressiveness. Compared to XML, YAML is less verbose and has a simpler syntax. In contrast to JSON, YAML allows for more human-friendly and readable data representation. It achieves this through the use of indentation and whitespace instead of character delimiters.

Practical Uses of YAML

YAML can be used in various ways within Python applications. Some common use cases include:

  • Configuration files: YAML files can store application settings, providing a more user-friendly and manageable alternative to plain text or INI files.
  • Data serialization: YAML can be used to store and exchange data between different programming languages and systems.
  • Testing: YAML can be used to define test scenarios and data sets in a format that is easy to read and maintain.
  • Documentation: YAML can be used to structure and document data models, making it easier for developers to understand and work with complex structures.

YAML Syntax

YAML uses a simple and intuitive syntax that is easy to read and write. It consists of key-value pairs, lists, and nested structures. Here’s an example YAML document:

name: John Doe
age: 25
street: 123 Main Street
city: Anytown
state: Example State

In this example, the document represents a person’s information, including their name, age, and address. The indentation and the use of colons indicate the structure and hierarchy of the data.

Unique Features

YAML provides some unique features that make it stand out compared to other data formats. Some of these features include:

  • Support for multiple data types: YAML supports various data types, including strings, numbers, booleans, dates, and even complex data structures like arrays and dictionaries.
  • Self-referential anchors and aliases: YAML allows for the reuse of common data elements using references, making it easier to manage and maintain large and complex documents.
  • Inline data structures: YAML supports the definition of arrays and dictionaries inline within a single line, providing more compact and readable code.

Getting Started With YAML in Python

Now that we have a basic understanding of YAML, let’s dive into using it in Python. To start working with YAML in Python, we will use the PyYAML library. Before we can use PyYAML, we need to install it.

Install the PyYAML Library

To install PyYAML, open a terminal or command prompt and run the following command:

Terminal window
pip install pyyaml

Once PyYAML is installed, we can start using it in our Python code.

Read and Write Your First YAML Document

To read and write YAML documents in Python, we need to use the yaml module from the PyYAML library. Here’s an example that demonstrates how to read and write a YAML document:

import yaml
# Read YAML from a file
with open('data.yaml', 'r') as f:
data = yaml.load(f, Loader=yaml.Loader)
# Modify the data
# Write YAML to a file
with open('modified_data.yaml', 'w') as f:
yaml.dump(data, f)

In this example, we first load the YAML document from a file using the load() function. We can then modify the data as needed. Finally, we dump the modified data back to a file using the dump() function.

Loading YAML Documents in Python

Once we have a YAML document, we can load it into Python and work with its data. PyYAML provides various options for loading YAML documents, such as choosing the loader class and handling insecure features.

Choose the Loader Class

PyYAML provides multiple loader classes that can handle different formats of YAML documents. The most commonly used loader classes are SafeLoader and Loader. The SafeLoader is the default and is recommended for loading untrusted YAML documents, while the Loader provides more features but may be vulnerable to certain security issues. Here’s an example that demonstrates how to choose the loader class:

data = yaml.load(yaml_string, Loader=yaml.SafeLoader) # Use SafeLoader for untrusted documents

Compare Loaders’ Features

Different loader classes provide different levels of security and features. The SafeLoader is designed to handle untrusted YAML documents and restricts the execution of certain potentially dangerous Python code. On the other hand, the Loader class provides more flexibility and features but may allow the execution of arbitrary Python code. When working with untrusted YAML documents, it is recommended to use the SafeLoader to minimize security risks.

Load a Document From a String, a File, or a Stream

PyYAML allows us to load YAML documents from various sources, such as strings, files, or streams. Here’s an example that demonstrates loading a document from a string:

yaml_string = """
name: John Doe
age: 25
data = yaml.load(yaml_string, Loader=yaml.Loader)

In this example, we have a YAML document represented as a string. We can pass the string to the load() function along with the desired loader class to load the document into Python.

Dumping Python Objects to YAML Documents

Apart from loading YAML documents, PyYAML also allows us to convert Python objects to YAML documents. This is useful when we want to serialize our Python data to a YAML format. Here’s an example that demonstrates how to dump a Python object to a YAML document:

data = {
'name': 'John Doe',
'age': 25,
yaml_string = yaml.dump(data, Dumper=yaml.Dumper)

In this example, we have a Python dictionary data that we want to convert to a YAML document. We can use the dump() function along with the Dumper class to achieve this. The resulting YAML document will be stored as a string in the yaml_string variable.


YAML is a versatile and human-readable data format that can be a valuable addition to your Python projects. With the PyYAML library, working with YAML in Python becomes straightforward and convenient. In this tutorial, we covered various aspects of working with YAML in Python, including reading and writing YAML documents, loading YAML documents, and dumping Python objects to YAML documents.

By leveraging PyYAML, you can handle YAML data seamlessly in your Python applications, improving their configuration, data exchange, and documentation capabilities. Keep exploring the power of YAML and PyYAML to enhance your Python projects.