Install & Compatibility
Where this runs
tested against v1.7.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 0.485s · 29.2MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 3.5s · import 0.450s · 29MB
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse_yaml_raw_as
✓ from pydantic_yaml import parse_yaml_raw_as
to_yaml_str
✓ from pydantic_yaml import to_yaml_str
YamlModel
✓ from pydantic_yaml import YamlModel
✗ from pydantic_yaml import YamlModel (for Pydantic >= 2.x)
The `YamlModel` and `YamlModelMixin` base classes were removed in `pydantic-yaml` v1 for Pydantic v2 and later; use `parse_yaml_raw_as` and `to_yaml_str` directly instead. This functionality may be re-added for Pydantic < 2.x in future `pydantic-yaml` v1 releases.
YamlModelMixin
✓ from pydantic_yaml import YamlModelMixin
✗ from pydantic_yaml import YamlModelMixin (for Pydantic >= 2.x)
The `YamlModel` and `YamlModelMixin` base classes were removed in `pydantic-yaml` v1 for Pydantic v2 and later; use `parse_yaml_raw_as` and `to_yaml_str` directly instead. This functionality may be re-added for Pydantic < 2.x in future `pydantic-yaml` v1 releases.
This example demonstrates how to define a Pydantic model with nested structures and enums, then serialize an instance to a YAML string, and finally deserialize that YAML string back into a Pydantic model using `pydantic-yaml`'s `to_yaml_str` and `parse_yaml_raw_as` functions. It also shows how Pydantic validators are preserved.
from enum import Enum
from pydantic import BaseModel, validator
from pydantic_yaml import parse_yaml_raw_as, to_yaml_str
class MyEnum(str, Enum):
a = "a"
b = "b"
class InnerModel(BaseModel):
fld: float = 1.0
class MyModel(BaseModel):
x: int = 1
e: MyEnum = MyEnum.a
m: InnerModel = InnerModel()
@validator("x")
def _chk_x(cls, v: int) -> int:
assert v > 0
return v
m1 = MyModel(x=2, e="b", m=InnerModel(fld=1.5))
# Dump to YAML string
yml_string = to_yaml_str(m1, add_comments=True)
print("\n--- Dumped YAML ---\n", yml_string)
# Parse YAML string back into model
m2 = parse_yaml_raw_as(MyModel, yml_string)
print("\n--- Parsed Model ---\n", m2)
assert m1 == m2
Debug
Known issues
breakingPydantic-YAML v1 introduces breaking changes regarding the `YamlModel` and `YamlModelMixin` base classes. For Pydantic v2 (and later), these mixin classes have been removed. Users should instead directly use the `parse_yaml_raw_as` and `to_yaml_str` functions.fixMigrate from inheriting `YamlModel` or `YamlModelMixin` to directly calling `pydantic_yaml.parse_yaml_raw_as(YourModel, yaml_data)` and `pydantic_yaml.to_yaml_str(your_instance)`.
affects: pydantic-yaml >= 1.0.0 with Pydantic >= 2.0.0
gotchaPydantic-YAML requires an underlying YAML parser (like `ruamel.yaml` or `PyYAML`) to be explicitly installed. Installing `pydantic-yaml` alone will not provide YAML parsing capabilities.fixInstall with optional dependencies: `pip install pydantic-yaml[ruamel]` (recommended) or `pip install pydantic-yaml[pyyaml]`.
affects: All versions
breakingSupport for Python 3.7 has been dropped. The library now requires Python 3.10 or newer.fixUpgrade your Python environment to 3.10 or newer. If you must use Python 3.7, `pydantic-yaml` version `1.1.3` is the last compatible release.
affects: pydantic-yaml >= 1.2.0 (specifically from release after 1.1.3)
gotchaWhile `pydantic-yaml` leverages Pydantic's JSON dumping internally, direct YAML-specific configuration options (beyond indentation) are limited. More specific YAML configuration is planned for a future major version (v2).fixCurrently, configure YAML output using `to_yaml_str` keyword arguments like `indent`. For more advanced YAML-specific serialization, manual intervention with `ruamel.yaml` or `PyYAML` might be necessary.
affects: All v1.x versions
Errors
Common errors & fixes
ImportError: cannot import name 'YamlModel' from 'pydantic_yaml'
This error often occurs because the necessary YAML parsing backend (like PyYAML or ruamel.yaml) was not installed alongside pydantic-yaml, or due to compatibility issues with Pydantic v2 where `YamlModel` was temporarily removed or its usage changed in certain pydantic-yaml versions.
fixEnsure you install pydantic-yaml with its optional dependencies, for example: `pip install pydantic-yaml[pyyaml,ruamel]` or `pip install pydantic-yaml[ruamel]` (if you prefer ruamel.yaml). If using Pydantic v2, ensure your pydantic-yaml version supports it, or adapt to using `parse_yaml_raw_as` or `parse_yaml_file_as` methods directly instead of inheriting from `YamlModel` if it's no longer available in your pydantic-yaml version.
ValidationError: 1 validation error for Test setting_2 -> 0 -> sublist value is not a valid list (type=type_error.list)
This is a Pydantic `ValidationError` indicating that the YAML data provided does not conform to the expected type or structure defined in your Pydantic model. In this specific example, a field expected to be a list received a non-list type.
fixReview your YAML input data and compare it against your Pydantic model definition. Correct the YAML structure or values to match the model's schema, ensuring all fields have the correct data types and formats.
ModuleNotFoundError: No module named 'yaml'
This error indicates that the underlying YAML parsing library, typically PyYAML, is not installed in your Python environment. Pydantic-yaml relies on a separate YAML parser to handle YAML data.
fixInstall a YAML parsing library such as PyYAML: `pip install PyYAML`. Alternatively, install `ruamel.yaml` if preferred: `pip install ruamel.yaml`. To avoid such issues, install pydantic-yaml with its recommended extras: `pip install pydantic-yaml[pyyaml]` or `pip install pydantic-yaml[ruamel]`.
AttributeError: 'model' object has no attribute '__fields_set__'
This `AttributeError` in a Pydantic model (which `pydantic-yaml` models inherit from) typically occurs when you override the `__init__` method in your model without correctly calling `super().__init__(**data)` or `BaseModel.__init__(self, **data)`. Pydantic's internal initialization process, which sets up attributes like `__fields_set__`, is then bypassed.
fixIf you need to override `__init__`, ensure you call the parent `BaseModel`'s initializer within your custom `__init__` method. For example: `super().__init__(**data)` or `BaseModel.__init__(self, **data)`. Often, custom logic can be handled with Pydantic validators (`@field_validator`, `@model_validator`) instead of `__init__` overrides.
Upgrade
Version history
1.7.0latest on PyPI · released Jun 21, 2026
Audit
Dependencies
pydanticrequiredCore dependency for defining data models.
ruamel.yamloptionalRecommended YAML parser for dumping and loading; either this or PyYAML is required for functionality.
PyYAMLoptionalAlternative YAML parser for dumping and loading; either this or ruamel.yaml is required for functionality.