pydantic_yaml

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 on this page — 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

pydantic-yaml on PyPI

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

Evidence: pydantic_yaml-1.7.0-py3-none-any.whl

Keywords: pydantic, yaml

Tags

More Software Development packages