For ROS users, PlotJuggler’s real test is not CSV — it is the recordings the robots already produce: ROS 1 .bag files, ROS 2 bags, and MCAP files. Both PlotJuggler lines open them, but by different routes, and confusing the routes is the main source of “it will not open my bag” frustration. This tutorial maps the routes honestly — what PJ3 does through its ROS plugin set, what PJ4 reads natively — then walks the opening workflow. It assumes a working install; ROS users who have not installed yet should start with the ROS 2 install guide. All guides are collected on the Tutorials hub.
The three recording types, in one paragraph each
- ROS 1 bags (
.bag). The original rosbag format: messages recorded from ROS 1 topics into a single file. In PlotJuggler, opening them is a PJ3 + ROS plugins workflow — the plugins are what understand the bag and expose its topics as series. - ROS 2 bags (rosbag2). ROS 2’s recorder stores recordings in its own layout, with MCAP among its storage options. The fact-base position is precise here: rosbag2/MCAP support in the PJ3 world lives in the ROS 2 / MCAP plugin set for PlotJuggler.
- MCAP files. A container format for timestamped, topic-structured recordings, used well beyond ROS. This is where the generations split: PJ3 reaches MCAP through that plugin set, while PJ4 lists MCAP as a natively supported file format — and can even attempt to read corrupted MCAP files, a capability added during the 3.999.x previews.
Which line should open your file?
| Your file | Route | Notes |
|---|---|---|
| ROS 1 .bag | PJ3 with the ROS plugins | Install via the ROS packages — see the ROS 2 install guide for the package model and distro list |
| ROS 2 bag (rosbag2) | PJ3 with the ROS 2 plugin set | The plugins line (v2.3+) supports ROS 2; ROS 1 plugin support is frozen in older versions |
| MCAP from a ROS 2 recording | PJ3 plugin set, or PJ4 natively | PJ4 reads MCAP directly as a file format; PJ3 needs the plugin set installed |
| MCAP from a non-ROS source | PJ4 natively | MCAP is on PJ4’s file list alongside CSV, Parquet, ULog, LeRobot, MP4, PCD and PLY |
Before you open anything: the install check
Most failures happen before the file is involved. On the PJ3 route, PlotJuggler and its ROS plugins arrive together through the ROS packages — sudo apt install ros-$ROS_DISTRO-plotjuggler-ros, launched with ros2 run plotjuggler plotjuggler, for the distributions the ROS Index lists (humble, jazzy, kilted, lyrical, rolling). If you installed a standalone PJ3 binary without the ROS plugin set, bag files have no loader and will not open — that is an install gap, not a corrupt file. The full walkthrough is the ROS 2 install guide in our Install section. On the PJ4 route, no ROS install is needed for MCAP files themselves, because MCAP reading is built into the application’s file support.
The opening workflow, step by step
- Load the recording by dragging it into the PlotJuggler window — the same drag-and-drop workflow as any other file. For a rosbag2 recording, you open the recording as the unit it was recorded as, rather than hunting for a single data file inside it.
- Let the loader enumerate the topics. A bag is many message streams in one container; the loader presents the topics, and the numeric fields inside those messages become the plottable series. Large bags expose a lot of series — that is normal.
- Choose deliberately. Find the topics your question is about (the command topic and the measured topic, the sensor and the estimate) and ignore the rest for now. Plotting everything is how people conclude, wrongly, that the tool is cluttered.
- Drag the fields onto plots. Overlay commanded vs measured on one plot; put diagnostics on their own plot below. From here the workflow is the standard one from Getting Started — navigate the timeline, add transforms, save the view.
- Save a layout. Bag investigations repeat: the same topics, the same arrangement, the next recording. Capture it once with layouts and reopen it against tomorrow’s bag.
Working across recordings
One bag is rarely the whole story. The natural follow-ups all have their own tutorials: overlay yesterday’s and today’s bags to see what a change actually did with comparing multiple bag files; fix recordings that started their clocks at different moments with time offsets; and compute the series the bag does not contain — error signals, magnitudes, rates — with Lua custom functions. If the data is still being produced, the same topics can also be watched live through the ROS topic streaming covered in the streaming tutorial.
When a bag will not open
- “No loader” behaviour on PJ3. Almost always the missing ROS plugin set — install the ROS package route above rather than reinstalling the standalone app.
- An MCAP that opens in PJ4 but not PJ3 (or the reverse expectation). Check which route your install actually has; the generations genuinely differ here, as the table above shows.
- A damaged MCAP. PJ4 added the ability to attempt reading corrupted MCAP files during its preview cycle — a damaged recording that a strict reader rejects is worth one attempt in PJ4 before you declare it lost.
- Everything opens, nothing is findable. A workflow problem, not a file problem: narrow to the topics for your question, name a layout, and reuse it.
Files for both lines, with checksums, are on the Download page; the rest of the series is on the Tutorials hub.