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-database compression_mode: FILE zstd envelopes (*.db3.zstd)

Any combination of these is accepted transparently.

bagwiz is built and run through pixi — no system ROS 2 install needed.

bagwiz provides first-class support for the long-term-support (LTS) ROS 2 distributions — Humble, Jazzy, and Lyrical; pixi.toml exposes one environment per distro.

1. Install pixi once, then reopen your shell so pixi is on PATH:

   curl -fsSL https://pixi.sh/install.sh | bash

2. Build bagwiz against a distro. The first build downloads that distro's packages and compiles bagwiz; later builds are incremental:

   pixi run -e humble build     # or: jazzy | lyrical

   pixi run build (no -e) targets Humble, the default environment. Each distro builds into its own build/<distro> and install/<distro>, so builds for several distros can coexist.

3. Install a bagwiz launcher on your PATH — plus tab completion — so you can run it from anywhere without typing pixi run:

   pixi run -e humble install   # builds, then installs ~/.local/bin/bagwiz + completion

   This installs the launcher and shell completion for your current shell in one step, always overwriting any existing copies. Use the same -e <distro> you built with (a bare pixi run install targets Humble, the default environment). Set BAGWIZ_INSTALL_DIR to change the destination, or BAGWIZ_DISTRO to target a different built distro. At run time, BAGWIZ_DISTRO=<distro> still switches which built distro the launcher uses.

4. Verify the install — bagwiz should now be on your PATH:

   bagwiz --help

   If the command is not found, make sure the install directory (default ~/.local/bin) is on your PATH.

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, then point BAGWIZ_OVERLAY at it (colon-separated for several workspaces) before running bagwiz:

BAGWIZ_OVERLAY=/path/to/my_msgs_ws pixi run -e humble run -- walk my.mcap /topic

The overlay's install/setup.bash is layered on top of the distro, so bagwiz finds your custom message definitions and typesupport at run time 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:

bagwiz <subcommand> --help is always available and reflects the same options documented in the per-command pages.

pixi run install already installs completion for your current shell (see step 3 of Installation). To install it manually, or for a different shell, bagwiz complete <shell> generates a completion script for bash, zsh, or fish. Pass --install to write it to the shell's standard location automatically (parent directories are created):

bagwiz complete bash --install
bagwiz complete zsh  --install   # remember to put ~/.zsh/completions on $fpath
bagwiz complete fish --install

Without --install the script is printed to stdout, so you can pipe it anywhere:

bagwiz complete bash > ~/.local/share/bash-completion/completions/bagwiz

Open a new shell, or source the generated file in the current shell:

source ~/.local/share/bash-completion/completions/bagwiz

Apache-2.0. See LICENSE.