Skip to main content

Quick Start

Get from install to architecture graph in under 2 minutes.

1. Install​

pipx install ros2inspector

pipx keeps the CLI isolated and exposes ros2inspector on your PATH, so there is no virtual environment to activate. See Installation if you need to install or configure pipx.

2. Scan your workspace​

Point ros2inspector at a supported ROS2 source workspace:

ros2inspector scan ~/robot_ws

Output:

  Scanning workspace...  ████████████████████  100%

  Packages Found
  ┌──────────────────────┬─────────┬──────────────┬───────┐
  │ Name                 │ Version │ Type         │ Score │
  ├──────────────────────┼─────────┼──────────────┼───────┤
  │ navigation2          │ 1.2.0   │ ament_cmake  │  94   │
  │ slam_toolbox         │ 2.6.0   │ ament_cmake  │  88   │
  │ robot_state_pub      │ 3.1.0   │ ament_python │  97   │
  └──────────────────────┴─────────┴──────────────┴───────┘

  ✓ 3 packages found  ·  Workspace health: 93/100

3. List all nodes​

ros2inspector nodes

This lists nodes detected from supported static Python and C++ patterns:

  ┌─────────────────────┬──────────────┬──────────┬─────────────────────────┐
  │ Node                │ Package      │ Language │ Publishers              │
  ├─────────────────────┼──────────────┼──────────┼─────────────────────────┤
  │ bt_navigator        │ navigation2  │ cpp      │ /cmd_vel, /waypoints    │
  │ slam_node           │ slam_toolbox │ cpp      │ /map, /pose             │
  │ robot_state_pub     │ robot_state… │ python   │ /robot_description      │
  └─────────────────────┴──────────────┴──────────┴─────────────────────────┘

4. Generate a graph​

Export to Mermaid (embeddable in any Markdown file):

ros2inspector graph comms --format mermaid

Or view an interactive HTML graph in your browser:

ros2inspector viz

This generates ros2inspector_graph.html and opens it automatically.

5. Filter by package​

Focus on a single package:

ros2inspector nodes -p navigation2
ros2inspector graph deps --format mermaid -p navigation2

6. Export to JSON​

Machine-readable output for scripting or CI integration:

ros2inspector nodes --format json > nodes.json
ros2inspector graph full --format json > graph.json

Common recipes​

Check workspace health​

ros2inspector scan ~/robot_ws
# Look at the Score column — 90+ is healthy

Find all publishers of a topic​

ros2inspector nodes --format json | python3 -c "
import json, sys
data = json.load(sys.stdin)
for n in data:
    if any(ep.get('name') == '/cmd_vel' for ep in n.get('publishers', [])):
        print(f'{n[\"package\"]}/{n[\"name\"]} publishes /cmd_vel')
"

Save a graph to a file​

ros2inspector graph comms --format dot -o architecture.dot
dot -Tpng architecture.dot -o architecture.png

CI diff (detect architecture changes)​

ros2inspector graph full --format json -o graph-before.json
# ... make changes ...
ros2inspector graph full --format json -o graph-after.json
diff graph-before.json graph-after.json

Next steps​