rostree 0.3.0

██████╗  ██████╗ ███████╗████████╗██████╗ ███████╗███████╗
██╔══██╗██╔═══██╗██╔════╝╚══██╔══╝██╔══██╗██╔════╝██╔════╝
██████╔╝██║   ██║███████╗   ██║   ██████╔╝█████╗  █████╗
██╔══██╗██║   ██║╚════██║   ██║   ██╔══██╗██╔══╝  ██╔══╝
██║  ██║╚██████╔╝███████║   ██║   ██║  ██║███████╗███████╗
╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝   ╚═╝  ╚═╝╚══════╝╚══════╝

Explore ROS 2 package dependencies from the command line (CLI, TUI, library).

Full demo reel · how the demo was made

Docs: docs/README.md — overview, package discovery, dependency trees, usage, development.

Quick start

pip install rostree
source /opt/ros/<distro>/setup.bash   # and/or your workspace install/setup.bash
rostree                               # interactive TUI

Why it is fast

A ROS dependency graph is a DAG, not a tree: rcutils sits under almost every branch. Expanding each path separately is exponential — a 159-package workspace printed 68,081 lines at depth 7, and never finished without a depth limit.

rostree expands each package once, where it first appears, and references it elsewhere (↩ see above), the way cargo tree does with (*). Package discovery happens once per run instead of once per node, and manifests are parsed once.

Nothing is hidden: every edge is still shown, once. --full restores the fully expanded tree if you want it.

CLI commands

rostree                      # Launch interactive TUI
rostree scan                 # Scan host for ROS 2 workspaces
rostree list --by-source     # List packages grouped by source
rostree list -f nav2         # Filter the package list

rostree tree rclcpp          # Dependency tree
rostree tree rclcpp -r -d 3  # Runtime deps only, 3 levels
rostree tree rclcpp --json   # Machine-readable

rostree why nav2_bringup rcutils   # How did this get into my tree?
rostree rdeps rclcpp               # What depends on this package?
rostree check                      # Cycles + unresolved deps (non-zero exit for CI)

rostree graph rclcpp --render png       # PNG via Graphviz
rostree graph rclcpp --render svg --open
rostree graph -w ~/ros2_ws --render png # Whole workspace
rostree graph rclcpp -f mermaid         # Mermaid text

TUI

rostree tui                  # Interactive terminal UI
rostree tui rclcpp           # Start on a package's tree

/ filters every package as you type, Enter opens a tree, v flips to "what depends on this", t switches between runtime and all dependencies, and ? shows the full keymap. Scanning and tree building run off the UI thread, and rows are created as you expand them, so nothing blocks.

Python API

from rostree import list_known_packages, get_package_info, build_tree, scan_workspaces
from rostree.api import build_graph, reverse_dependencies, tree_stats

packages = list_known_packages()
root = build_tree("rclcpp", runtime_only=True)
print(tree_stats(root))                  # nodes, packages, depth, repeats, missing

graph = build_graph("nav2_bringup")      # the resolved DAG, linear to build
print(graph.cycles(), sorted(graph.missing))

print(reverse_dependencies("rclcpp"))    # who depends on it

Links

• How the system works
• How packages are found (workspaces, AMENT_PREFIX_PATH, COLCON_WORKSPACE)
• Dependency trees (package.xml, the package index, repeat collapsing)
• Usage (CLI, TUI keys, API)
• Development (layout, pre-commit, CI)
• Changelog