Registry / serialization / pydantic-avro

pydantic-avro

library0.10.0pypypi✓ verified 25d ago

Pydantic-Avro is a Python library designed to convert Pydantic classes into Avro schemas, and vice-versa, allowing for seamless integration between Pydantic models and Avro data formats. It is actively maintained with frequent updates, with the latest stable version being 0.10.0.

serialization data

pip install pydantic-avro

github ↗package ↗

INSTALL

IMPORT

SIG · PYDANTIC-AVRO

pydantic-avro

serializationpythonv0.10.0

Install

3.2s avg

Import

374ms

Disk

26MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.10.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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.392s · 27.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.2s · import 0.356s · 28MB

26MB installed

● package 26MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AvroBase

✓ from pydantic_avro.base import AvroBase

Field

✓ from pydantic import Field

Required for Pydantic field definitions, including Avro type overrides.

This example demonstrates how to define a Pydantic model inheriting from `AvroBase` and then generate its corresponding Avro schema. It also shows how to use `pydantic.Field` for adding descriptions and overriding default Avro type mappings (e.g., `datetime` to a 'string' Avro type explicitly).

import json from typing import Optional from pydantic import Field from pydantic_avro.base import AvroBase class User(AvroBase): id: int name: str = Field(..., description="User's full name") email: Optional[str] = None is_active: bool = True creation_date: str = Field(..., avro_type="string", description="Date of user creation in ISO format") # Generate Avro schema avro_schema = User.avro_schema() print(json.dumps(avro_schema, indent=2))

Debug

Known issues

breakingPydantic-Avro supports Pydantic versions >=1.4 and <3.0. While this range covers both Pydantic V1 and V2, mixing V1 and V2 models within an application using Pydantic-Avro can lead to unexpected behavior or incompatibilities due to significant architectural and API changes in Pydantic V2. Ensure consistent Pydantic versioning across your codebase, or leverage Pydantic's V1 compatibility layer (`from pydantic import v1 as pydantic_v1`) carefully.

fix

Standardize your application's Pydantic version. If migrating to V2, update all models to V2 syntax. If using both, consult Pydantic's migration guide for interoperability strategies and ensure `pydantic-avro`'s behavior is as expected with mixed environments.

affects: <0.10.0

gotchaGenerating an Avro schema for Pydantic fields defined with `typing.Literal` containing only a single string value (e.g., `Literal['only_value']`) may fail or produce incorrect schemas due to a known issue.

fix

As a workaround, consider using a `Union` with a constant `str` for single-literal cases, or explicitly defining an `enum` Avro type if appropriate, until the issue is resolved.

affects: All versions up to 0.10.0

breakingPrior to version `0.9.0`, `pydantic-avro` had issues with correctly converting unsupported list values and tuples in Pydantic models to their corresponding Avro schema types, potentially leading to errors during schema generation.

fix

Upgrade to `pydantic-avro` version `0.9.0` or later to ensure proper handling of list and tuple types in Avro schema generation.

affects: <0.9.0

gotchaVersion `0.9.3` introduced a new `mode` parameter to the `AvroBase.avro_schema()` method, allowing users more fine-grained control over how schemas are generated (e.g., for specific Avro features or compatibility). Users upgrading from older versions might not be aware of this enhanced functionality.

fix

Review the documentation for the `mode` parameter in `AvroBase.avro_schema()` and incorporate it if you require more control or specific Avro schema generation behaviors.

affects: <0.9.3

gotchaFrom version `0.8.0` onwards, `pydantic-avro` provides explicit support for overriding the default Avro type conversion using `pydantic.Field(..., avro_type="your_avro_type")`. If you previously implemented custom logic or workarounds for specific type mappings, you can now use this native method.

fix

Migrate any custom type conversion logic to use the `avro_type` argument within `pydantic.Field` for cleaner and officially supported type overrides.

affects: <0.8.0

Errors

Common errors & fixes

AttributeError: 'NoneType' object has no attribute 'get' (or similar AttributeError within pydantic_avro/base.py during avro_schema generation)

This error often occurs when pydantic-avro encounters complex Pydantic types, particularly nested lists, tuples, or unions, that it cannot properly convert into a corresponding Avro schema type, leading to an unexpected `None` value being processed.

fix

Simplify the Pydantic model's complex types, for example, by breaking down deeply nested unions or tuples into simpler, directly supported types, or by ensuring enum values are strings if an enum is involved. Upgrading `pydantic-avro` to the latest version might also resolve issues with previously unsupported complex types, as fixes have been implemented for some of these cases.

pydantic_core._pydantic_core.ValidationError: 1 validation error for [model_name] [field_name] Input should be None [type=none_required, input_value=[...], input_type=dict]

This validation error arises when `avsc_to_pydantic` generates Pydantic models from an Avro schema where a field and a nested record (class) are given the same name. Pydantic then struggles to correctly parse the input when instantiating the generated model, expecting `None` due to the naming conflict.

fix

Modify the Avro schema to ensure unique names for fields and nested records, or manually adjust the generated Pydantic model to resolve the naming collision. A proposed fix is to include parent names in the generated class naming scheme to ensure uniqueness.

ModuleNotFoundError: No module named 'pydantic_avro'

The `pydantic-avro` library has not been installed in your current Python environment, or the environment where the code is being run does not have access to the installed package.

fix

Install the library using pip: `pip install pydantic-avro`.

Upgrade

Version history

0.10.0latest on PyPI · released Feb 6, 2026

Audit

Dependencies

pydanticrequiredCore dependency for defining data models, supporting versions >=1.4,<3.0.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/godatadriven/pydantic-avro ↗

packagehttps://pypi.org/project/pydantic-avro/ ↗