Install & Compatibility
Where this runs
tested against v0.70.7 · 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
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AvroModel
✓ from dataclasses_avroschema import AvroModel
AvroModel
✓ from dataclasses_avroschema import AvroModel
✗ from dataclasses_avroschema.schema_generator import SchemaGenerator
As of v0.14.0, the recommended way is to inherit from AvroModel, not use SchemaGenerator directly.
types.Enum
✓ import enum; class MyEnum(enum.Enum): ...
✗ favorite_colors: types.Enum = types.Enum([...])
Prior to v0.23.0, `types.Enum` was used. Now, standard Python `enum.Enum` (potentially mixed with `str`) is expected.
This quickstart demonstrates how to define a dataclass with `AvroModel`, including enums, lists, and dictionaries. It shows how to generate the Avro schema, serialize a Python instance to Avro binary format, and then deserialize it back into a Python object.
import dataclasses
import enum
import typing
from dataclasses_avroschema import AvroModel
class FavoriteColor(enum.Enum):
BLUE = "Blue"
YELLOW = "Yellow"
GREEN = "Green"
@dataclasses.dataclass
class User(AvroModel):
"An User"
name: str
age: int
pets: typing.List[str]
accounts: typing.Dict[str, int]
favorite_color: FavoriteColor
country: str = "Argentina"
address: typing.Optional[str] = None
class Meta:
namespace = "User.v1"
aliases = ["user-v1", "super user"]
# Generate Avro schema
avro_schema = User.avro_schema()
print("Avro Schema:")
print(avro_schema)
# Create an instance
user_instance = User(
name="John Doe",
age=30,
pets=["dog", "cat"],
accounts={"bank": 1000, "crypto": 500},
favorite_color=FavoriteColor.BLUE,
country="USA",
address="123 Main St"
)
# Serialize to Avro binary
serialized_data = user_instance.serialize()
print("\nSerialized data (bytes):", serialized_data)
# Deserialize from Avro binary
deserialized_user = User.deserialize(serialized_data)
print("\nDeserialized user:", deserialized_user)
avro-schema-gen --version
Errors
Common errors & fixes
AttributeError: '_SpecialForm' object has no attribute 'avro_schema_to_python'
This error typically occurs when using `typing.Any` as a field's type within an `AvroModel`, as `typing.Any` is not a directly supported Avro type and cannot be introspected by the library to generate a schema.
fixReplace `typing.Any` with a concrete Avro-compatible type (e.g., `str`, `int`, `bool`) or a `typing.Union` of specific types, including `None` for optional fields.
Incorrect Serialization and Deserialization of Union Types (e.g., deserialized object does not match expected type, incorrect binary output for union types)
When Avro `union` types have subschemas with identical field names and types, the underlying `fastavro` library (used by `dataclasses-avroschema`) may struggle to correctly infer the target type during serialization or deserialization because the dictionary representation loses the specific class information, leading to ambiguous type resolution.
fixFor deserialization issues, set `dacite_config = {'strict': True}` in the `Meta` class of your `AvroModel` to enforce stricter type matching during the deserialization process. For serialization, ensure union member types are sufficiently distinct, or if using `avro-json`, the type is explicitly added to the union field data. ModuleNotFoundError: No module named 'dataclasses'
This fundamental Python error indicates that the `dataclasses` module cannot be found. `dataclasses-avroschema` relies on Python's built-in `dataclasses` which were introduced in Python 3.7. If you are using an older Python version (e.g., 3.6), the module is not natively available.
fixUpgrade your Python version to 3.7 or newer. If you must use Python 3.6, install the `dataclasses` backport: `pip install dataclasses`.
AttributeError: exception raised when trying to generate schema from AvroModel itself and not a subclass of it
This error occurs when `avro_schema()` is called directly on the base `AvroModel` class (e.g., `AvroModel.avro_schema()`) instead of on a user-defined dataclass that inherits from `AvroModel`. The base class does not have concrete schema fields defined to generate a valid Avro schema.
fixAlways define a dataclass that inherits from `dataclasses_avroschema.AvroModel` and then call the `avro_schema()` method on that specific subclass, e.g., `MyUserClass.avro_schema()`.
Upgrade
Version history
0.70.7latest on PyPI · released Aug 20, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or higher.
pydanticoptionalOptional, for integrating with Pydantic models.
faust-streamingoptionalOptional, for integrating with Faust Records.
fakeroptionalOptional, for generating fake data for models.
dc-avrooptionalOptional, for command-line interface tools.