A fast CLI for analyzing, processing, and extracting data from ROS 2 rosbags entirely offline — without spinning up a ROS graph. rosbag2 inputs are read through a unified backend that spans three independent dimensions:
- Storage format — MCAP (
*.mcap) or SQLite3 (*.db3) - Layout — a rosbag2 directory or a bare single file
- Compression — uncompressed, rosbag2
compression_mode: MESSAGE, MCAP per-chunk compression, or whole-databasecompression_mode: FILEzstd envelopes (*.db3.zstd)
Any combination of these is accepted transparently.
bagwiz is built and run through pixi — no system ROS 2 install needed.
-
Install pixi once, then reopen your shell so
pixiis onPATH:curl -fsSL https://pixi.sh/install.sh | bash -
Build bagwiz for a distro. bagwiz supports ROS 2 Humble and Jazzy; each has CPU and CUDA environments.
pixi run -e humble build-core # basic features pixi run -e humble build-full # includes advanced features such as `map`
Use
build-fullonly when you need features likebagwiz map. The default environment is Jazzy, sopixi run build-coreis equivalent topixi run -e jazzy build-core. -
Install a
bagwizlauncher on yourPATHso you can run it from anywhere:pixi run -e humble install # installs ~/.local/bin/bagwizThis also installs shell completion for your current shell. It does not build; run the build from step 2 first. Use the same
-e <distro>you built with. To switch distros, runpixi run -e <distro> installagain. -
Verify the install:
bagwiz --help
If the command is not found, make sure the install directory (default
~/.local/bin) is on yourPATH.
Bags whose topics use message types beyond the standard stack need the matching
ROS 2 message packages available at run time. Build those packages in your own
colcon workspace and source its install/setup.bash before running bagwiz:
source /path/to/my_msgs_ws/install/setup.bash
bagwiz walk my.mcap /topicSourcing the overlay sets AMENT_PREFIX_PATH and LD_LIBRARY_PATH, so bagwiz
finds the msg/*.msg definitions and can dlopen() the introspection typesupport
at runtime without a rebuild. Build overlays against the same distro so their
libraries stay ABI compatible with bagwiz.
bagwiz is a single executable that dispatches to one subcommand per
invocation. Click through for full usage, options, and examples:
| Command | What it does |
|---|---|
bagwiz ls |
List topics in a ROS 2 rosbag (add -l for per-topic counts and average frequencies). |
bagwiz walk |
Interactively walk a ROS 2 topic's messages as decoded YAML. |
bagwiz convert |
Repack a ROS 2 rosbag between storage backends/layouts, or convert topic message types (NavSatFix → pose). |
bagwiz topic |
Keep (keep), drop (drop), or rename (rename) topics in a ROS 2 rosbag. |
bagwiz trim |
Trim a ROS 2 rosbag to a time window given as offsets from the bag start (e.g. --start 5s --end 90s), or align it to the time span of selected topics (--align). Windows are evaluated on header.stamp by default (--stamp recv for record time). |
bagwiz cam-info |
Replace (replace) one or more CameraInfo topics' calibration with values from a camera_calibration YAML file, recompute (recompute-p) the projection matrix from the intrinsics, or dump (dump) a topic's calibration back out to YAML. |
bagwiz generate |
Generate non-rosbag media from a rosbag — e.g. render an image topic to a video (video). |
bagwiz traj |
Dump a topic's pose trajectory to TUM, or join a trajectory file back into a bag. |
bagwiz tf |
Inspect and edit TF in a ROS 2 rosbag: frame tree, static-transform resolution, static-TF copy, and interactive transform walk. |
bagwiz pcd |
PointCloud2 topic processing: concatenate multiple LiDAR topics into one (concat) via static TF + time sync, or motion-deskew one or more topics from an external pose topic (undistort). |
bagwiz map |
LiDAR map generation and viewing: map slam, map viewer. Optional build. |
bagwiz check |
Find rosbags whose storage is corrupt / unreadable, and optionally delete them. |
bagwiz complete |
Generate a shell completion script (bash, zsh, fish). |
bagwiz <subcommand> --help is always available and reflects the same
options documented in the per-command pages.
bagwiz reads a handful of optional environment variables to override
defaults — logging verbosity (BAGWIZ_LOG_LEVEL), decoder backend
(BAGWIZ_DECODER), color output (NO_COLOR), message-package overlays
(AMENT_PREFIX_PATH), and the installed launcher's distro
(BAGWIZ_DEFAULT_DISTRO), among others. None are required for normal use. See
the full reference in docs/environment.md.
Apache-2.0. See LICENSE.