Beginner’s Guide: Safely Load YAML in Python with safe_load

1. How to Load YAML in Python? | Article Overview and Target Audience

To Those Who Want to Work with YAML in Python

• Web apps or scripts externalize configuration files
• Parse Docker Compose and Kubernetes configuration files with Python
• Manage machine learning framework parameters with YAML

What You’ll Learn in This Article

• Basic structure and characteristics of YAML files
• How to load in Python (using safe_load())
• Common errors and how to address them
• Reading multiple documents and practical examples with configuration files

Target Audience

• Beginners to intermediate users who want to try YAML with Python
• Developers who need to work with configuration files
• Those who are unsure about how to use PyYAML
• People who want to learn more about safe_load() and error handling

2. What is YAML? | Simple Comparison of Differences and Features with JSON

What is YAML?

Differences with JSON

Benefits of YAML

• Intuitive syntax: similar to Python indentation, making the structure easy to grasp
• Comments can be written: convenient for adding notes to configuration files
• Not redundant: no need for braces or double quotes like in JSON
• Human‑friendly: readable and editable even by non‑engineers

Typical Use Cases for YAML

• Docker Compose (docker-compose.yml)
• Kubernetes configuration files (definitions of Pods and Services)
• CI/CD tools (GitHub Actions, GitLab CI, etc.)
• Machine learning libraries (such as PyTorch Lightning and Hydra)
• Web app and script configuration files

3. Preparing to Work with YAML in Python | Installing PyYAML

What is PyYAML?

How to Install PyYAML

pip install pyyaml

Using a Virtual Environment is Recommended

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On Windows
venvScriptsctivate
# On macOS/Linux
source venv/bin/activate

# Install PyYAML
pip install pyyaml

How to Verify the Installation

import yaml
print(yaml.__version__)

4. Basic: How to Read YAML Files in Python (Using safe_load)

Most basic loading method: safe_load()

Sample YAML file (config.yaml)

app:
  name: SampleApp
  version: 1.0.0
debug: true
servers:
  - host: localhost
    port: 8000
  - host: example.com
    port: 443

Example loading code in Python

import yaml

with open('config.yaml', 'r', encoding='utf-8') as f:
    config = yaml.safe_load(f)

print(config)

Output example (Python dict format)

{
  'app': {'name': 'SampleApp', 'version': '1.0.0'},
  'debug': True,
  'servers': [
    {'host': 'localhost', 'port': 8000},
    {'host': 'example.com', 'port': 443}
  ]
}

open() function: specifying encoding is important

One point: using the with statement

5. Differences between safe_load and load | Cautions for loading YAML in Python

safe_load() and load(): What’s the difference?

safe_load() Features (Safe Loading)

import yaml

with open('config.yaml', 'r', encoding='utf-8') as f:
    data = yaml.safe_load(f)

• Basic function to use
• High security (does not load arbitrary Python objects)
• Limited to basic data types (dicts, lists, strings, numbers, etc.)
• Raises an error when attempting to load unknown types or objects

load() Features (Flexible but Risky)

import yaml

with open('config.yaml', 'r', encoding='utf-8') as f:
    data = yaml.load(f, Loader=yaml.FullLoader)

• Can interpret YAML more flexibly
• Can reconstruct Python objects (e.g., functions, class instances, etc.)
• Because of security risks, specifying a Loader is required

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

Types of Loaders (Differences in Security and Flexibility)

Conclusion: Usually use safe_load()

6. Common Errors and Their Solutions | Pitfalls of Loading YAML in Python

Why You Might Stumble When Loading YAML

1. Syntax Errors Caused by Indentation Mistakes

Example: YAML with Indentation Error

user:
  name: Alice
    age: 30

Example Error Message:

yaml.scanner.ScannerError: mapping values are not allowed here

Solution:

• Use a consistent indentation of 2–4 spaces (do not use tabs).
• Indent child elements deeper than their parent elements.

2. Garbled Text Caused by File Encoding

Error Example:

UnicodeDecodeError: 'cp932' codec can't decode byte...

Solution:

with open('config.yaml', 'r', encoding='utf-8') as f:
    data = yaml.safe_load(f)

• Explicitly specifying encoding='utf-8' resolves the issue.
• This is especially easy to forget on Windows environments.

3. Incorrect File Path / Missing File

Error Example:

FileNotFoundError: [Errno 2] No such file or directory: 'config.yaml'

Solution:

• Verify that the path is specified as an absolute path or a correct relative path.
• Check for typos in the filename or extension.
• Ensure the file is in the same directory as the script.

4. safe_load Returns None

Example:

# This file contains no settings

Result:

data = yaml.safe_load(f)
print(data)  # Output: None

Solution:

• Make sure the file contains valid YAML data.
• Returning None for a file with only comments or whitespace is normal behavior.

5. Parse Errors in Overly Complex YAML Structures

Solution:

• Validate the syntax incrementally (verify small sections at a time).
• Catching yaml.YAMLError exceptions and inspecting the detailed messages is recommended.

try:
    with open('config.yaml', 'r', encoding='utf-8') as f:
        data = yaml.safe_load(f)
except yaml.YAMLError as e:
    print(f"YAML loading error: {e}")

Summary: When Errors Occur, Calmly Check Syntax and Environment

• Whether the indentation is correct (no tabs used).
• Whether the file encoding is UTF-8.
• Whether the file exists.
• Whether the YAML content is correctly written.

7. Advanced: How to Load YAML Files with Multiple Documents (safe_load_all)

YAML can contain multiple documents in a single file

Example of a multi-document YAML file (multi.yaml)

# Server configuration 1
---
server:
  host: localhost
  port: 8080

# Server configuration 2
---
server:
  host: example.com
  port: 443

How to use yaml.safe_load_all()

import yaml

with open('multi.yaml', 'r', encoding='utf-8') as f:
    documents = yaml.safe_load_all(f)
    for doc in documents:
        print(doc)

Execution result (example output):

{'server': {'host': 'localhost', 'port': 8080}}
{'server': {'host': 'example.com', 'port': 443}}

Note the difference from safe_load()

You can also convert the loaded documents into a list

with open('multi.yaml', 'r', encoding='utf-8') as f:
    documents = list(yaml.safe_load_all(f))

Note: Not all YAML files support multiple documents

8. Supplement: Key Points for Using YAML as a Configuration File

Why is YAML suitable for configuration files?

• Environment configuration for web applications (production / development / testing)
• Hyperparameter settings for machine learning
• Switching script behavior
• Management of external dependencies such as API keys (note: be careful with handling confidential information)

Example of a practical YAML configuration file

app:
  name: MyApp
  mode: production

logging:
  level: INFO
  file: logs/app.log

database:
  host: localhost
  port: 5432
  user: admin
  password: secret

Hierarchical configuration using nested structures

env:
  dev:
    db: dev-db.local
    debug: true
  prod:
    db: prod-db.server
    debug: false

You can clarify intent with comments

# Application mode setting (one of dev, test, production)
mode: production

Code example for loading YAML at runtime (advanced)

import yaml

with open('settings.yaml', 'r', encoding='utf-8') as f:
    config = yaml.safe_load(f)

app_name = config['app']['name']
mode = config['app']['mode']
db_host = config['database']['host']

Caution: Handle confidential information carefully

• Prevent committing to the repository with .gitignore
• Combine with files like .env and keep only references in YAML
• Apply encryption and access restrictions

9. Frequently Asked Questions (FAQ)

Q1. Between YAML and JSON, which is easier to handle in Python?

Q2. Should you avoid using yaml.load()?

Q3. Why does the loaded YAML content become empty (None)?

# This file has not been configured yet

Q4. Can you reuse values in a YAML file (like variables)?

default: &defaults
  timeout: 30
  retries: 3

service1:
  <<: *defaults
  host: service1.local

service2:
  <<: *defaults
  host: service2.local

Q5. Japanese characters become garbled on Windows. How can I fix this?

with open('config.yaml', 'r', encoding='utf-8') as f:
    data = yaml.safe_load(f)

Q6. How should I read a YAML file that is split into multiple configuration blocks?

---
app: App1
port: 3000
---
app: App2
port: 4000

with open('multi.yaml', 'r', encoding='utf-8') as f:
    for doc in yaml.safe_load_all(f):
        print(doc)

10. Summary | Master YAML Loading in Python

Reviewing YAML Loading from Basics to Advanced

• Installing PyYAML: To work with YAML in Python, you first need pip install pyyaml.
• Basic loading: Using yaml.safe_load() lets you safely and easily load YAML into dictionaries or lists.
• Error handling: Indentation and encoding mistakes are common issues. Syntax checking and encoding='utf-8' are important.
• Difference from load(): If safety is a priority, you should use safe_load(). load() requires specifying an appropriate Loader.
• Handling multiple documents: With safe_load_all(), you can flexibly process multiple configuration blocks within a single file.
• Practicality as a configuration file: YAML’s readability and flexibility make it ideal for configuration management in Python projects.

Next steps: Leverage YAML even more

• Writing to YAML files: Automatic generation of configuration files using yaml.dump()
• Bidirectional conversion with JSON: Handy when integrating with web APIs or external services
• Combining with .env files or environment variables: Building a more secure configuration management approach
• Automating configuration loading: A mechanism that dynamically loads the appropriate configuration file based on the environment when the app starts