---
id: pydantic-compat
version: "0.1.2"
license: BSD 3-Clause License
license_treatment: permissive
maintenance: active
---

# pydantic-compat — Compatibility layer for pydantic v1/v2

License: permissive · Maintenance: active · Downloads: 80.3K/mo

## 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 above — 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

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

- License: BSD 3-Clause License (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 80.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pydantic v1 v2 compatibility, pydantic version adapter, cross-version pydantic support, pydantic api translation, pydantic migration helper, unified pydantic interface, pydantic compatibility layer, pydantic, compatibility-layer, version-bridge

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