pydantic-compat

What it is and what it does

pydantic-compat is a compatibility layer that lets you write pydantic models using either v1 or v2 API names while supporting both pydantic versions in a single codebase. It works by providing a mixin class and adapter functions that translate between the two APIs—for example, mapping `obj.dict()` to `obj.model_dump()` or vice versa depending on which pydantic version is installed. This eliminates the need for version-specific conditionals and boilerplate throughout your library code.

The package is not a full semantic bridge: it translates names and provides basic compatibility for common operations like validation, serialization, and schema access, but does not attempt to hide deeper behavioral differences between v1 and v2. You still need to test your code against both pydantic versions and understand what's changing under the hood. It's designed for library authors who want to support a range of pydantic versions without forcing users to pin a specific version.

Use it for:

• Library author supporting both pydantic v1 and v2 without version pinning or deprecation warnings
• Migrating a codebase from pydantic v1 to v2 incrementally while maintaining compatibility
• Defining models that work seamlessly when users have either pydantic version installed
• Reducing conditional version-checking code in model definitions and validation logic

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides compatibility mixins and adapters to use either pydantic v1 or v2 API names in a single codebase, regardless of which pydantic version is installed.

Yes, if you are a library author needing to support both pydantic v1 and v2 in the same codebase. The low install friction and active maintenance make it a practical choice. However, be aware that this is a name adapter, not a full semantic bridge—you will still need to test against both pydantic versions and handle any deeper API differences yourself. Not necessary if you can pin pydantic to a single version.

Install

pydantic-compat on PyPI

pip install pydantic-compat

uv add pydantic-compat

poetry add pydantic-compat

Installing pydantic-compat

Before you install

Low install friction with only two runtime dependencies (importlib-metadata and pydantic). Actively maintained as of 2026-08-03, though the last release was in 2023-10-24.

License in practice

BSD 3-Clause License (permissive) allows use in most commercial and open-source projects without significant restrictions.

Quickstart

from pydantic import BaseModel
from pydantic_compat import PydanticCompatMixin, field_validator

class MyModel(PydanticCompatMixin, BaseModel):
    x: int
    @field_validator('x', mode='after')
    def check_x(cls, v):
        return v

obj = MyModel(x=42)
data = obj.model_dump()  # works in both v1 and v2

Verify before relying

• Whether the package's API coverage is sufficient for your specific pydantic usage patterns beyond the documented examples
• How well custom type handling works across both pydantic versions when using this adapter

Package facts

Evidence: pydantic_compat-0.1.2-py3-none-any.whl

Tags

More Application Frameworks packages