---
id: pydantic-yaml
version: "1.7.0"
license: MIT License Copyright (c) 2020 Anatoly Makarevich Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# pydantic_yaml — YAML reading/writing for Pydantic models

License: permissive · Maintenance: active · Downloads: 2.5M/mo

## What it is and what it does

Pydantic-YAML bridges Pydantic's data validation framework with YAML serialization. It provides two main functions: to_yaml_str() converts a validated Pydantic model instance into YAML text, and parse_yaml_raw_as() parses YAML text back into a typed model with full validation. The package leverages Pydantic's existing JSON serialization machinery and wraps ruamel-yaml for YAML handling, so it inherits Pydantic's validator support, nested model composition, and type safety.

Typical usage involves defining a Pydantic BaseModel, instantiating it with data, calling to_yaml_str() to export it as human-readable YAML, and later calling parse_yaml_raw_as() to load and re-validate YAML files. The package also supports optional comment generation from model docstrings and field descriptions, custom YAML writer configuration via ruamel.yaml instances, and works with both Pydantic v1 and v2 (including dataclass support in v2).

Use it for:

- Load configuration files in YAML format into typed Pydantic models with automatic validation and type coercion.
- Export application state or settings as human-readable YAML while maintaining schema validation on round-trip.
- Generate YAML documentation or examples from Pydantic models using comment generation from docstrings.
- Migrate data between YAML and JSON formats while preserving type safety through a single Pydantic model definition.
- Validate YAML input in CLI tools or configuration management systems using Pydantic's full validator ecosystem.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Pydantic-YAML adds YAML serialization and deserialization to Pydantic models, letting you read and write validated data structures as YAML files or strings.

Yes. The package is actively maintained, has no known vulnerabilities, low install friction, and fills a clear gap: it lets you use Pydantic's validation and typing with YAML files. If your project needs to read or write YAML with schema validation, this is the standard solution. The MIT license poses no restrictions.

## Install

pip install pydantic-yaml
uv add pydantic-yaml
poetry add pydantic-yaml

## Installing pydantic_yaml

Before you install: Low install friction: pure Python wheel with only three runtime dependencies (pydantic, ruamel-yaml, typing-extensions). Actively maintained with a release 54 days ago and no known vulnerabilities.

License in practice: MIT License permits commercial and private use, modification, and redistribution with minimal restrictions—standard permissive terms suitable for most projects.

Quickstart:

pip install pydantic-yaml

from pydantic import BaseModel
from pydantic_yaml import parse_yaml_raw_as, to_yaml_str

class MyModel(BaseModel):
    x: int = 1
    name: str = "test"

m = MyModel(x=2, name="example")
yaml_str = to_yaml_str(m)
m2 = parse_yaml_raw_as(MyModel, yaml_str)

Requires Python 3.10 or later (package specifies >=3.10,<3.15).

Verify before relying:

- Whether comment generation from docstrings (add_comments=True) works reliably with all field types and nested models.
- Performance characteristics when handling large YAML documents or deeply nested structures.
- Compatibility with Pydantic v2 dataclass dumping in production scenarios beyond the documented example.

## Package facts

- License: MIT License Copyright (c) 2020 Anatoly Makarevich Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 2.5M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pydantic yaml serialization, yaml to pydantic model, pydantic yaml parsing, serialize pydantic to yaml, yaml validation pydantic, pydantic yaml config, yaml-serialization, pydantic-integration, config-management

[View on SkillFed](https://skillfed.io/packages/pydantic-yaml) · [View on PyPI](https://pypi.org/project/pydantic-yaml/)