Install & Compatibility
Where this runs
tested against v0.5.4 · 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.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.4s · import 0.134s · 49MB
47MB installed
● package 47MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
read_protobuf_messages
✓ from mcap_protobuf.reader import read_protobuf_messages
Writer
✓ from mcap_protobuf.writer import Writer
✗ from mcap.mcap0.writer import Writer as McapWriter; from mcap_protobuf.schema import register_schema
Older versions (e.g., v0.0.4) and low-level usage might involve manually registering schemas with `mcap.mcap0.writer`. The `mcap_protobuf.writer.Writer` provides a simplified, higher-level API.
This quickstart demonstrates how to write and read Protobuf messages to/from an MCAP file using `mcap-protobuf-support`. Before running, you would typically compile your `.proto` files into Python classes using `protoc` (e.g., `protoc --python_out=. your_message.proto`). The example uses dummy classes to simulate compiled Protobuf messages for executability. The `Writer` automatically handles schema registration, and `read_protobuf_messages` iterates through decoded messages.
import sys
from mcap_protobuf.writer import Writer
from mcap_protobuf.reader import read_protobuf_messages
# Assuming you have a compiled protobuf message, e.g., 'my_message_pb2.py'
# from my_message_pb2 import SimpleMessage, ComplexMessage
# For demonstration, we'll create dummy classes that mimic protobuf messages
class SimpleMessage:
def __init__(self, data):
self.data = data
def SerializeToString(self):
return f'SimpleMessage(data="{self.data}")'.encode('utf-8') # Dummy serialization
@classmethod
def FromString(cls, data):
# Dummy deserialization - in a real scenario, this would parse protobuf bytes
import re
match = re.search(r'data="([^"]+)"', data.decode('utf-8'))
return cls(match.group(1)) if match else cls('N/A')
class ComplexMessage:
def __init__(self, fieldA, fieldB):
self.fieldA = fieldA
self.fieldB = fieldB
def SerializeToString(self):
return f'ComplexMessage(fieldA="{self.fieldA}", fieldB="{self.fieldB}")'.encode('utf-8') # Dummy serialization
@classmethod
def FromString(cls, data):
# Dummy deserialization
import re
match = re.search(r'fieldA="([^"]+)".*fieldB="([^"]+)"', data.decode('utf-8'))
return cls(match.group(1), match.group(2)) if match else cls('N/A', 'N/A')
# To make this runnable without actual .proto compilation, we need to mock
# how the `Writer` would register these messages. In a real scenario,
# SimpleMessage and ComplexMessage would be actual protobuf generated classes.
# ---- Writing MCAP file with Protobuf messages ----
output_file = "example.mcap"
with open(output_file, "wb") as f, Writer(f) as mcap_writer:
# In a real application, SimpleMessage would be from `your_proto_file_pb2`
mcap_writer.write_message(
topic="/simple_messages",
message=SimpleMessage(data="Hello MCAP protobuf world #1!"),
log_time=1000,
publish_time=1000,
)
complex_message = ComplexMessage(fieldA="Field A 1", fieldB="Field B 1")
mcap_writer.write_message(
topic="/complex_messages",
message=complex_message,
log_time=2000,
publish_time=2000,
)
print(f"Wrote messages to {output_file}")
# ---- Reading MCAP file with Protobuf messages ----
def register_dummy_message_classes(reader):
# This function mocks how actual protobuf message classes would be registered
# For real use, you'd import your compiled protobuf message classes
reader.register_message("SimpleMessage", SimpleMessage)
reader.register_message("ComplexMessage", ComplexMessage)
print(f"\nReading messages from {output_file}:")
for msg_info in read_protobuf_messages(output_file):
# The msg_info.proto_msg will be an instance of your actual Protobuf class
print(f"Topic: {msg_info.topic}, Message: {msg_info.proto_msg.data if hasattr(msg_info.proto_msg, 'data') else msg_info.proto_msg.fieldA}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'google.protobuf'
The `protobuf` Python package, which is a core dependency for `mcap-protobuf-support`, is not installed or not accessible in the current Python environment.
fixInstall the `protobuf` package: `pip install protobuf` or `pip install mcap-protobuf-support` (which includes protobuf as a dependency).
ModuleNotFoundError: No module named 'your_message_pb2'
You are trying to import a Protobuf message class (e.g., `your_message_pb2`) but have not yet compiled your `.proto` definition files into Python source files using the `protoc` compiler.
fixCompile your Protobuf definition files: `protoc --python_out=. your_message.proto` (replace `your_message.proto` with your actual proto file).
AttributeError: type object 'MethodOptions' has no attribute 'RegisterExtension'
This error typically indicates an incompatibility or version mismatch between the `protobuf` Python library and other `google` client libraries or generated Protobuf code, often due to conflicting installations or an outdated `protobuf` package.
fixUpgrade the `protobuf` package to the latest version: `pip install --upgrade protobuf`. If conflicts persist, consider creating a clean virtual environment.
mcap.exceptions.McapProtobufDecodeError: Could not decode protobuf message
The `mcap-protobuf-support` library failed to decode a Protobuf message from an MCAP file. This can happen if the schema in the MCAP file doesn't match the Protobuf message definition being used for decoding, or if the message data itself is corrupted or malformed.
fixEnsure that the Protobuf definition files used to generate the Python classes for decoding precisely match the schemas written into the MCAP file. Verify the integrity of the MCAP file and the correctness of the message data being read.
Upgrade
Version history
0.5.4latest on PyPI · released Dec 24, 2025
Audit
Dependencies
mcaprequiredCore Python MCAP library; `mcap-protobuf-support` is a helper library built on top of it.
google-protobufrequiredRequired for Protobuf message definitions and serialization.