ros2 unbag - fast ROS 2 bag export for any format

ros2 unbag is a powerful ROS 2 tool featuring an intuitive GUI and flexible CLI for extracting topics from .db3 or .mcap bag files into formats like CSV, JSON, PCD, images, and more.

• 🎨 Intuitive GUI interface for interactive bag exploration and export configuration
• ⚙️ Full-featured ROS 2 CLI plugin: ros2 unbag <args> for automation and scripting
• 🔌 Pluggable export routines enable export of any message to any type
• 🔧 Custom processors to filter, transform or enrich messages

• ⏱️ Time‐aligned resampling (last

  nearest)

• 🚀 Multi‐process export with adjustable CPU usage
• 💾 JSON config saving/loading for repeatable workflows

[!TIP] Quick install: sudo apt update && sudo apt install ros-<distro>-unbag

ROS binary packages are now the official distribution channel. See the distro badges above for current availability; installation details and a temporary pip fallback are provided below.

Table of Contents

• Introduction
• Installation
  • Install via apt (Recommended)
  • From Source
  • Docker
• Quick Start
  • GUI Mode
  • CLI Mode
• Documentation
  • Export Routines - Built-in and custom export formats
  • Processors - Message transformation and filtering
  • Advanced Usage - Config files, resampling, CPU tuning
• Acknowledgements

Introduction

The GUI makes it easy to inspect bag contents, select topics, configure export formats, build processor chains, and manage resampling. For automation and scripting workflows, the CLI provides the same export capabilities through command-line arguments or JSON configuration files.

It comes with export routines for all message types (sensor data, point clouds, images). You need a special file format or message type? Add your own export plugin for any ROS 2 message or format, and chain custom processors to filter, transform or enrich messages (e.g. drop fields, compute derived values, remap frames).

Optional resampling synchronizes your data streams around a chosen master topic—aligning each other topic either to its last‑known sample (“last”) or to the temporally closest sample (“nearest”)—so you get a consistent sample count in your exports.

For high‑throughput workflows, ros2 unbag can spawn multiple worker processes and lets you tune CPU usage. Your topic selections, processor chains, export parameters and resampling mode (last or nearest) can be saved to and loaded from a JSON configuration, ensuring reproducibility across runs.

Whether you prefer the GUI for interactive exploration or ros2 unbag <args> for automated pipelines, you have a flexible, extensible way to turn bag files into the data you need.

Installation

Install via apt (Recommended)

ros2 unbag is released as a binary package for ROS 2 Humble, Jazzy, Kilted, Lyrical, and Rolling. Install it from the ROS apt repositories:

sudo apt update
sudo apt install ros-<distro>-unbag

Replace <distro> with your ROS 2 distribution (e.g. humble, jazzy, kilted, lyrical, or rolling). Once installed, source your ROS 2 installation and ros2 unbag is ready to use.

ROS binary repositories are updated on ROS build farm sync cycles, so a new release may not be available for every distribution immediately. The distro badges at the top of this README show the versions currently available via apt. If your distro has not been synced yet, use the temporary PyPI fallback:

pip install ros2-unbag

[!WARNING] PyPI/pip is no longer the official distribution channel; use the ROS binary package once it becomes available for your distro.

From source

1. Create a ROS 2 workspace and clone the repository into src:

   mkdir -p ros2_ws/src
   git clone https://github.com/ika-rwth-aachen/ros2_unbag.git ros2_ws/src/ros2_unbag
   cd ros2_ws
   

1. Source your ROS 2 installation:

   source /opt/ros/<distro>/setup.bash
   

File truncated at 100 lines see the full file