Home/Python Guide

JSON to YAML Python: Complete Guide with Code Examples

To convert JSON to YAML in Python, use the PyYAML library with json.loads() and yaml.dump(). Install PyYAML with pip install pyyaml, then use: yaml.dump(json.loads(json_string), default_flow_style=False).

Installing PyYAML

PyYAML is the standard Python library for reading and writing YAML files. It's actively maintained, well-documented, and handles all YAML 1.1 specification features.

Installation with pip

bash
# Install PyYAML using pip
pip install pyyaml

# For Python 3 specifically
pip3 install pyyaml

# Install in a virtual environment
python -m venv myenv
source myenv/bin/activate  # Linux/Mac
myenv\Scripts\activate     # Windows
pip install pyyaml

Verify Installation

bash
# Check if PyYAML is installed correctly
python -c "import yaml; print(yaml.__version__)"

# Expected output: 6.0.1 (or current version)

Alternative Installation Methods

bash
# Using conda
conda install pyyaml

# Using poetry
poetry add pyyaml

# Using pipenv
pipenv install pyyaml

PyYAML comes pre-installed with many Python distributions including Anaconda. Check if it's already available before installing.

Basic JSON to YAML Conversion

Converting a JSON string to YAML requires two steps: parse the JSON into a Python object, then serialize that object to YAML format.

Simple String Conversion

python
import json
import yaml

# JSON string to convert
json_string = '''
{
    "name": "my-application",
    "version": "1.0.0",
    "description": "A sample application",
    "author": "Developer Name"
}
'''

# Step 1: Parse JSON to Python dict
data = json.loads(json_string)

# Step 2: Convert to YAML
yaml_output = yaml.dump(data, default_flow_style=False)

print(yaml_output)

Output

yaml
author: Developer Name
description: A sample application
name: my-application
version: 1.0.0

Converting Nested JSON

python
import json
import yaml

json_string = '''
{
    "application": {
        "name": "web-service",
        "version": "2.0.0"
    },
    "database": {
        "host": "localhost",
        "port": 5432,
        "credentials": {
            "username": "admin",
            "password": "secret"
        }
    },
    "features": ["auth", "logging", "caching"]
}
'''

data = json.loads(json_string)
yaml_output = yaml.dump(data, default_flow_style=False)

print(yaml_output)

Output

yaml
application:
  name: web-service
  version: 2.0.0
database:
  credentials:
    password: secret
    username: admin
  host: localhost
  port: 5432
features:
- auth
- logging
- caching

Converting JSON Files to YAML Files

When working with files rather than strings, use json.load() and write the YAML output to a file object.

Basic File Conversion

python
import json
import yaml

def convert_json_to_yaml(json_filepath, yaml_filepath):
    """
    Convert a JSON file to YAML format.

    Args:
        json_filepath: Path to input JSON file
        yaml_filepath: Path to output YAML file
    """
    # Read JSON file
    with open(json_filepath, 'r', encoding='utf-8') as json_file:
        data = json.load(json_file)

    # Write YAML file
    with open(yaml_filepath, 'w', encoding='utf-8') as yaml_file:
        yaml.dump(data, yaml_file, default_flow_style=False, allow_unicode=True)

    print(f"Converted {json_filepath} to {yaml_filepath}")

# Usage
convert_json_to_yaml('config.json', 'config.yaml')

Batch Conversion of Multiple Files

python
import json
import yaml
import os
from pathlib import Path

def batch_convert_json_to_yaml(input_dir, output_dir):
    """
    Convert all JSON files in a directory to YAML.

    Args:
        input_dir: Directory containing JSON files
        output_dir: Directory for YAML output files
    """
    # Create output directory if it doesn't exist
    Path(output_dir).mkdir(parents=True, exist_ok=True)

    # Process each JSON file
    for filename in os.listdir(input_dir):
        if filename.endswith('.json'):
            json_path = os.path.join(input_dir, filename)
            yaml_filename = filename.replace('.json', '.yaml')
            yaml_path = os.path.join(output_dir, yaml_filename)

            with open(json_path, 'r', encoding='utf-8') as f:
                data = json.load(f)

            with open(yaml_path, 'w', encoding='utf-8') as f:
                yaml.dump(data, f, default_flow_style=False)

            print(f"Converted: {filename} -> {yaml_filename}")

# Usage
batch_convert_json_to_yaml('./json_configs/', './yaml_configs/')

YAML to JSON Conversion in Python

Converting in the opposite direction uses yaml.safe_load() to parse YAML and json.dumps() to serialize to JSON.

Basic YAML to JSON

python
import json
import yaml

yaml_string = '''
name: my-application
version: "1.0.0"
database:
  host: localhost
  port: 5432
  ssl: true
features:
  - authentication
  - logging
  - caching
'''

# Parse YAML (always use safe_load for security)
data = yaml.safe_load(yaml_string)

# Convert to JSON with formatting
json_output = json.dumps(data, indent=2)

print(json_output)

Output

json
{
  "name": "my-application",
  "version": "1.0.0",
  "database": {
    "host": "localhost",
    "port": 5432,
    "ssl": true
  },
  "features": [
    "authentication",
    "logging",
    "caching"
  ]
}

Security Warning

Always use yaml.safe_load() instead of yaml.load() when parsing untrusted YAML content. The safe_load function prevents arbitrary code execution vulnerabilities.

python
# SAFE - use this for untrusted input
data = yaml.safe_load(yaml_content)

# UNSAFE - only use for trusted sources you control
data = yaml.load(yaml_content, Loader=yaml.FullLoader)

YAML Formatting Options

PyYAML's dump() function accepts multiple parameters to customize the output format.

Common Parameters

python
import yaml

data = {
    "users": [
        {"name": "Alice", "age": 30, "active": True},
        {"name": "Bob", "age": 25, "active": False}
    ],
    "settings": {
        "theme": "dark",
        "language": "en"
    }
}

# Block style (most readable)
print("=== Block Style ===")
print(yaml.dump(data, default_flow_style=False))

# Flow style (compact, JSON-like)
print("=== Flow Style ===")
print(yaml.dump(data, default_flow_style=True))

# Preserve key order (Python 3.7+)
print("=== Preserved Order ===")
print(yaml.dump(data, default_flow_style=False, sort_keys=False))

# Custom indentation
print("=== 4-Space Indent ===")
print(yaml.dump(data, default_flow_style=False, indent=4))

# Unicode support
print("=== Unicode Enabled ===")
print(yaml.dump({"message": "Hello 世界"}, allow_unicode=True))

Parameter Reference Table

ParameterDefaultDescription
default_flow_styleNoneFalse = block style, True = flow style
sort_keysTrueFalse preserves original key order
indent2Number of spaces for indentation
allow_unicodeFalseTrue enables Unicode characters
width80Maximum line width
explicit_startFalseTrue adds --- document start
explicit_endFalseTrue adds ... document end

Error Handling

Production code should handle potential errors during JSON parsing and YAML conversion.

Comprehensive Error Handling

python
import json
import yaml
from json import JSONDecodeError

def safe_json_to_yaml(json_string):
    """
    Safely convert JSON string to YAML with comprehensive error handling.

    Args:
        json_string: JSON data as string

    Returns:
        YAML string on success, error message on failure
    """
    # Validate input
    if not json_string or not json_string.strip():
        return "Error: Empty input provided"

    try:
        # Parse JSON
        data = json.loads(json_string)
    except JSONDecodeError as e:
        return f"JSON Error: {e.msg} at line {e.lineno}, column {e.colno}"
    except TypeError as e:
        return f"Type Error: {str(e)}"

    try:
        # Convert to YAML
        yaml_output = yaml.dump(
            data,
            default_flow_style=False,
            allow_unicode=True,
            sort_keys=False
        )
        return yaml_output
    except yaml.YAMLError as e:
        return f"YAML Error: {str(e)}"
    except Exception as e:
        return f"Unexpected Error: {str(e)}"

# Test with valid JSON
result = safe_json_to_yaml('{"name": "test", "value": 123}')
print(result)

# Test with invalid JSON
result = safe_json_to_yaml('{"invalid": }')
print(result)

Complete Working Examples

Example 1: One-Liner Conversion

python
import json, yaml

# JSON to YAML one-liner
json_to_yaml = lambda j: yaml.dump(json.loads(j), default_flow_style=False)

# YAML to JSON one-liner
yaml_to_json = lambda y: json.dumps(yaml.safe_load(y), indent=2)

# Usage
print(json_to_yaml('{"key": "value", "number": 42}'))
print(yaml_to_json('key: value\nnumber: 42'))

Example 2: Kubernetes Manifest Generator

python
import yaml

def create_k8s_deployment(name, image, replicas=1, port=80):
    """
    Generate Kubernetes deployment YAML from parameters.
    """
    deployment = {
        'apiVersion': 'apps/v1',
        'kind': 'Deployment',
        'metadata': {
            'name': name,
            'labels': {'app': name}
        },
        'spec': {
            'replicas': replicas,
            'selector': {
                'matchLabels': {'app': name}
            },
            'template': {
                'metadata': {
                    'labels': {'app': name}
                },
                'spec': {
                    'containers': [{
                        'name': name,
                        'image': image,
                        'ports': [{'containerPort': port}]
                    }]
                }
            }
        }
    }

    return yaml.dump(deployment, default_flow_style=False, sort_keys=False)

# Generate deployment
manifest = create_k8s_deployment(
    name='web-app',
    image='nginx:1.21',
    replicas=3,
    port=80
)
print(manifest)

Frequently Asked Questions

How do I convert JSON to YAML in Python?
Use PyYAML library: import json and yaml, then call yaml.dump(json.loads(json_string), default_flow_style=False) to convert JSON to YAML in Python. The default_flow_style=False parameter creates readable block-style YAML output.
What Python library converts JSON to YAML?
PyYAML is the most popular Python library for JSON to YAML conversion. Install it with pip install pyyaml and use yaml.dump() for conversion. It's actively maintained and handles the full YAML 1.1 specification.
How do I convert a JSON file to YAML file in Python?

Open the JSON file with json.load(), then write to YAML using yaml.dump() with a file object:

python
with open('input.json') as f:
    data = json.load(f)
with open('output.yaml', 'w') as f:
    yaml.dump(data, f, default_flow_style=False)
Is PyYAML safe to use?
Yes, when using yaml.safe_load() instead of yaml.load(). The safe_load function prevents arbitrary code execution when parsing untrusted YAML input. Always use safe_load for any YAML from external sources.
Can I preserve key order when converting JSON to YAML?
Yes, use yaml.dump(data, sort_keys=False) to preserve the original key order. This works reliably with Python 3.7+ where dictionaries maintain insertion order by default.
How do I handle Unicode characters in conversion?
Add allow_unicode=True to yaml.dump(): yaml.dump(data, allow_unicode=True). This prevents Unicode characters from being escaped and keeps them readable in the output.
What's the difference between yaml.load() and yaml.safe_load()?
yaml.safe_load() only parses standard YAML tags and is safe for untrusted input. yaml.load() can execute arbitrary Python code through YAML tags, making it dangerous for untrusted content. Always prefer safe_load().

Related Resources

Online Tools