Install & Compatibility
Where this runs
tested against v1.4.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
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.2s · import 0.079s · 50MB
48MB installed
● package 48MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
make_reader
✓ from mcap.reader import make_reader
✗ from mcap.mcap0.reader import make_reader
The `mcap.mcap0` path was used in older versions (e.g., 0.0.11) but is now internal; use `mcap.reader` for the public API.
Writer
✓ from mcap.writer import Writer
✗ from mcap.mcap0.writer import Writer
The `mcap.mcap0` path was used in older versions but is now internal; use `mcap.writer` for the public API.
read_protobuf_messages
✓ from mcap_protobuf.reader import read_protobuf_messages
DecoderFactory
✓ from mcap_ros1.decoder import DecoderFactory
read_ros2_messages
✓ from mcap_ros2.reader import read_ros2_messages
Writer (ROS2)
✓ from mcap_ros2.writer import Writer
This quickstart demonstrates how to write a simple MCAP file with JSON-encoded messages and then read it back using the `mcap` library's core reader and writer. It registers a schema and channel, adds a message, and iterates over messages to print their content.
import json
import sys
from time import time_ns
from mcap.writer import Writer
from mcap.reader import make_reader
file_path = "example.mcap"
# --- Writing an MCAP file ---
with open(file_path, "wb") as stream:
writer = Writer(stream)
writer.start(profile="x-my-profile", library="my-writer-v1")
schema_id = writer.register_schema(
name="sample",
encoding="jsonschema",
data=json.dumps({
"type": "object",
"properties": {
"sample": {
"type": "string"
}
}
}).encode(),
)
channel_id = writer.register_channel(
schema_id=schema_id,
topic="/sample_topic",
message_encoding="json",
)
writer.add_message(
channel_id=channel_id,
log_time=time_ns(),
data=json.dumps({"sample": "hello world"}).encode("utf-8"),
publish_time=time_ns(),
)
writer.finish()
print(f"Wrote {file_path}")
# --- Reading an MCAP file ---
with open(file_path, "rb") as f:
reader = make_reader(f)
for schema, channel, message in reader.iter_messages(topics=["/sample_topic"]):
print(f"Read: Topic='{channel.topic}' (Schema='{schema.name}'): {message.data.decode('utf-8')}")
mcap --version
Debug
Known issues
gotchaModules, variables, classes, and attributes prefixed with a single underscore (`_`) are considered internal API and may change between minor or patch releases without prior notice. Relying on them can lead to unexpected breakages.fixOnly use documented public API components (those without a leading underscore) to ensure forward compatibility and stability.
affects: All versions
gotchaReading topics from MCAP files that were converted from ROS 1 `.bag` files might exhibit slower performance compared to reading directly from the original `.bag` files using native ROS 1 tools.fixIf performance is critical for ROS 1 data, benchmark reading both the original `.bag` and the converted `.mcap` file. Consider using native `rosbag` tools for initial processing if the overhead of MCAP conversion/reading is prohibitive for your use case.
affects: All versions when reading converted ROS 1 data
gotchaThe `mcap` library provides raw message data (byte streams). Users are responsible for decoding complex or compressed payloads (e.g., images, point clouds) into usable Python objects using appropriate image processing or serialization libraries. The library does not automatically handle this decoding beyond schema registration.fixWhen consuming messages with complex data types, manually integrate external libraries (e.g., Pillow for images, `struct` for binary data, Protobuf/ROS message definitions for structured data) to parse the `message.data` byte array according to the `schema.encoding` and `channel.message_encoding`.
affects: All versions
gotchaThe core `mcap` Python library is primarily designed for creating new files or reading existing ones. Direct programmatic appending to an *already closed* MCAP file is not a officially supported operation and can lead to unexpected behavior or data corruption.fixFor continuous logging or adding data over time, design your application to either keep the writer stream open or create new MCAP files for each recording session. For post-processing scenarios where merging is needed, consider using the `mcap-cli` tool's `merge` command.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mcap'
The 'mcap' package is not installed in the Python environment.
fixInstall the package using 'pip install mcap'.
ModuleNotFoundError: No module named 'mcap_ros2'
The 'mcap_ros2' package is not installed in the Python environment.
fixInstall the package using 'pip install mcap_ros2'.
ImportError: cannot import name 'DecoderFactory' from 'mcap_ros2.decoder'
The 'DecoderFactory' class has been moved or renamed in the 'mcap_ros2.decoder' module.
fixUpdate the import statement to 'from mcap_ros2.decoder import DecoderFactory'.
AttributeError: module 'mcap_ros2.decoder' has no attribute 'DecoderFactory'
The 'DecoderFactory' class is not present in the 'mcap_ros2.decoder' module, possibly due to a version mismatch.
fixEnsure that the 'mcap_ros2' package is updated to the latest version using 'pip install --upgrade mcap_ros2'.
TypeError: 'NoneType' object is not callable
Attempting to call a function that is 'None', possibly due to a failed import or incorrect assignment.
fixVerify that all necessary modules are correctly imported and that functions are properly defined before calling them.
Upgrade
Version history
1.4.0latest on PyPI · released Jun 18, 2026
Audit
Dependencies
mcap-protobuf-supportoptionalRequired for reading and writing Protobuf-encoded messages.
mcap-ros1-supportoptionalRequired for reading and writing ROS 1 messages.
mcap-ros2-supportoptionalRequired for reading and writing ROS 2 messages.