Install & Compatibility
Where this runs
tested against v1.12.2 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.059s · 38.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.9s · import 0.052s · 47MB
40MB installed
● package 40MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
schema
✓ import avro.schema
✗ import avro.schema
parse
✓ from avro.schema import parse
✗ avro.schema.parse
This quickstart demonstrates how to define an Avro schema, serialize Python dictionaries (records) into an Avro data file (here, in-memory using `io.BytesIO`), and then deserialize them back into Python dictionaries. It uses `avro.schema.parse` to load the schema, `DataFileWriter` and `DatumWriter` to write, and `DataFileReader` and `DatumReader` to read.
import avro.schema
from avro.datafile import DataFileReader, DataFileWriter
from avro.io import DatumReader, DatumWriter
import io
# Define schema
schema_str = '''
{
"type": "record",
"name": "User",
"fields": [
{"name": "name", "type": "string"},
{"name": "favorite_number", "type": ["int", "null"]},
{"name": "favorite_color", "type": ["string", "null"]}
]
}
'''
schema = avro.schema.parse(schema_str)
# Prepare data
users = [
{"name": "Alyssa", "favorite_number": 256, "favorite_color": "red"},
{"name": "Ben", "favorite_number": 7, "favorite_color": "blue"},
{"name": "Charlie", "favorite_number": null, "favorite_color": "green"},
{"name": "David", "favorite_number": 42, "favorite_color": null}
]
# Write data to an in-memory Avro file
# Using io.BytesIO for an in-memory file-like object
output_stream = io.BytesIO()
writer = DataFileWriter(output_stream, DatumWriter(), schema)
for user in users:
writer.append(user)
writer.close()
# Reset stream position to read from the beginning
output_stream.seek(0)
# Read data from the in-memory Avro file
reader = DataFileReader(output_stream, DatumReader())
print("Reading Avro data:")
for user in reader:
print(user)
reader.close()
output_stream.close()
avro --version
Debug
Known issues
deprecatedThe `avro-python3` PyPI package is deprecated. Users should now install and use the `avro` package, which supports both Python 2 (legacy) and Python 3. The `avro-python3` package will be removed in the near future.fixEnsure you are installing `avro` (i.e., `pip install avro`). If migrating from `avro-python3`, be aware of minor API differences, such as function capitalization (e.g., `avro.schema.parse` vs `avro.schema.Parse`).
affects: <= 1.10.x of `avro-python3`, all versions of `avro`.
gotchaInstalling the `avro` package (intended for Python 3+) in older Python 2 environments or incorrectly expecting Python 2 behavior in Python 3 can lead to `SyntaxError` due to incompatible syntax (e.g., `except Exception, e:`).fixAlways use a Python 3 environment (>=3.9 as per package requirements) and ensure `pip install avro` is performed. The `avro` package has consolidated Python 3 support.
affects: Python 2.x environments attempting to use Python 3+ compatible `avro` library. Python 3 environments if `avro` (Python 2 intended) was mistakenly installed before version unification.
gotchaThe official Python Avro library is implemented in pure Python, which can lead to slow performance when processing large volumes of data or complex schemas. This is a common pain point for users.fixFor performance-critical applications, consider using alternative libraries like `fastavro` (available on PyPI: `pip install fastavro`), which uses C extensions for significantly improved speed. `fastavro` provides a similar API but may not support Avro RPC.
affects: All versions of the official `avro` library.
gotchaWhen reading Avro files, the reader's schema must be compatible with the writer's schema, adhering to Avro's schema evolution rules. Mismatched or missing fields (especially required ones) between reader and writer schemas can lead to errors or unexpected data during deserialization.fixCarefully manage schema evolution. Ensure that reader schemas are forward-compatible with writer schemas. For robust applications, always validate your data against the expected schema and handle potential schema resolution errors.
affects: All versions.
gotchaThe `NameError: name 'null' is not defined` occurs when using `null` (lowercase) as a value in Python code, instead of the Python keyword `None` (title case). This is a common mistake for users familiar with JSON or other languages, but it's a fundamental Python syntax error, not specific to the `avro` library itself. Avro serialization expects Python's `None` for null values.fixWhen creating Python dictionaries or objects that represent Avro data, always use the Python keyword `None` to represent null values. For example, instead of `"favorite_number": null`, use `"favorite_number": None`.
affects: All versions of the `avro` library, specifically when constructing data in Python.
gotchaUsing 'null' instead of 'None' in Python code will result in a `NameError`. Python's keyword for a null value is `None`, whereas 'null' is commonly used in JSON and other languages. This often occurs when directly embedding JSON-like structures into Python without conversion.fixReplace all instances of `null` with `None` in your Python code. For example, `{ 'key': null }` should be `{ 'key': None }`. When parsing actual JSON strings, use `json.loads()` to correctly convert `null` to `None`. affects: All Python versions and all versions of the `avro` library (as it pertains to user script syntax).
Upgrade
Version history
1.12.2latest on PyPI · released Aug 17, 2026
Audit
Dependencies
python-snappyoptionalOptional Snappy compression support
python-zstandardoptionalOptional Zstandard compression support