Install & Compatibility
Where this runs
tested against v0.11.5 · 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 4.9s · import 0.288s · 128MB
128MB installed
● package 128MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AnyReader
✓ from rosbags.highlevel import AnyReader
Primary high-level interface for reading rosbag files.
Stores
✓ from rosbags.typesys import Stores
Used to access predefined message type stores (e.g., ROS2_FOXY).
get_typestore
✓ from rosbags.typesys import get_typestore
Function to retrieve a message type store.
Reader
✓ from rosbags.rosbag2 import Reader
Specific reader for ROS2 bag files when high-level AnyReader is not sufficient.
Serde
✓ from rosbags.serde import Serde
✗ from rosbags.serde.serdes import Serde
The import path for Serde-related modules changed. Direct import from `rosbags.serde` is now preferred. Older paths like `rosbags.serde.serdes` were deprecated around version 0.9.20.
This quickstart demonstrates how to open a rosbag file (ROS1 or ROS2), iterate through its messages, and deserialize them using the high-level `AnyReader` interface. It includes explicit handling for type stores, which is crucial for correct message deserialization, especially if the bag does not contain complete message definitions or for custom message types. Remember to replace `test_rosbag_dir` with the actual path to your rosbag.
from pathlib import Path
from rosbags.highlevel import AnyReader
from rosbags.typesys import Stores, get_typestore
# Replace with the actual path to your rosbag file/directory
# For testing, you can create a dummy bag file or use an existing one.
# Example: bagpath = Path('./path/to/my_rosbag')
# Ensure the path points to the directory containing a ROS2 bag or a ROS1 .bag file.
bagpath = Path('test_rosbag_dir') # Placeholder, modify as needed
# Create a type store to use if the bag has no message definitions or for custom types.
# ROS2_FOXY is an example; choose the appropriate ROS distribution if needed.
typestore = get_typestore(Stores.ROS2_FOXY)
try:
# Create reader instance and open for reading.
with AnyReader([bagpath], default_typestore=typestore) as reader:
# Filter connections (topics) if desired. Here, we read all messages.
# connections = [x for x in reader.connections if x.topic == '/imu_raw/Imu']
print(f"Found {len(reader.connections)} connections (topics) in the bag.")
for connection in reader.connections:
print(f" Topic: {connection.topic}, Type: {connection.msgtype}")
message_count = 0
for connection, timestamp, rawdata in reader.messages():
# Deserialize the message data
msg = reader.deserialize(rawdata, connection.msgtype)
# Access message fields (example for a common message type)
# This assumes your message type has a 'header' and 'frame_id'
# Adapt based on the actual message types in your bag.
try:
if hasattr(msg, 'header') and hasattr(msg.header, 'frame_id'):
print(f"[{timestamp}] Topic: {connection.topic}, Frame ID: {msg.header.frame_id}")
else:
print(f"[{timestamp}] Topic: {connection.topic}, Message: {msg}")
except AttributeError:
print(f"[{timestamp}] Topic: {connection.topic}, Message: {msg}") # Fallback for messages without header
message_count += 1
if message_count >= 10: # Limit output for brevity
print("... (truncated after 10 messages)")
break
except FileNotFoundError:
print(f"Error: Bag file or directory not found at {bagpath}. Please create or specify a valid path.")
except Exception as e:
print(f"An error occurred: {e}")
rosbags --version
Debug
Known issues
breakingThe import paths for serialization/deserialization modules were refactored, specifically affecting imports from `rosbags.serde.serdes`. Code relying on these old paths will break.fixUpdate your imports to the new structure, typically importing directly from `rosbags.serde` or using the high-level `AnyReader` and its `deserialize` method which handles these internally. The official documentation's quickstart demonstrates the recommended approach using `rosbags.highlevel` and `rosbags.typesys`.
affects: >=0.9.20 (released 2024-02-29)
gotchaWhen reading rosbag files, especially those without embedded message definitions or containing custom message types, `rosbags` requires an explicit `Typestore` to correctly deserialize messages. Failing to provide an appropriate `default_typestore` can lead to deserialization errors or incorrect message interpretation.fixAlways provide a `default_typestore` (e.g., `get_typestore(Stores.ROS2_FOXY)`) to `AnyReader` or `Reader` instances. For custom message types, ensure they are registered with the `Typestore` or included in a custom message definition path.
affects: All versions
gotchaWhile `rosbags` itself is designed for efficient handling of bag files, processing extremely large rosbag files (e.g., hundreds of GBs or millions of messages) without care can still lead to high memory consumption, especially if users attempt to load all messages or connections into memory simultaneously. Iterators are provided for a reason.fixUtilize the iterator-based approach (e.g., `reader.messages()`) to process messages one by one rather than loading all messages at once. Filter connections using `reader.connections` to only process relevant topics. Ensure your processing logic within the loop is memory-efficient.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'rosbags'
The 'rosbags' library is not installed in your current Python environment.
rosbags.rosbag2.errors.Rosbag2Error: Failed to open rosbag2
The specified rosbag file either does not exist, the path is incorrect, or the file is corrupted/not a valid rosbag2 file.
fixVerify the file path and ensure the rosbag file is valid and accessible.
rosbags.rosbag2.errors.Rosbag2Error: Type description not found for '...' (e.g., 'std_msgs/msg/String')
The rosbags library cannot find the message definition for a specific message type encountered in the bag file, preventing deserialization.
fixEnsure the necessary ROS message packages are installed and sourced in your environment, or use `rosbags.typesys.register_types()` to provide custom message type definitions.
from rosbags.rosbag1 import Reader
Developers sometimes directly import format-specific low-level readers, but the high-level API provides a unified, format-agnostic interface for both ROS 1 and ROS 2 bags.
fixFor most general use cases, use `from rosbags.highlevel import Reader` to automatically handle both bag formats.
Upgrade
Version history
0.11.5latest on PyPI · released Aug 19, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.
numpyrequiredUsed for numerical data types and operations.
ruamel-yamlrequiredUsed for YAML parsing, especially for metadata files.
lz4optionalOptional dependency for LZ4 compression, used for Python < 3.14.
safelz4optionalOptional dependency for LZ4 compression, used for Python >= 3.14.
zstandardoptionalOptional dependency for Zstandard compression.
typing-extensionsrequiredRequired for type hints, version >=4.5.