Usage¶
CLI Commands¶
rostree (default: TUI)¶
rostree # Launch interactive TUI
rostree tui # Same as above
rostree tui rclpy # Start TUI with a specific package tree
rostree scan¶
Discover ROS 2 workspaces on the host machine.
rostree scan # Scan default locations (~/ros*_ws, /opt/ros/*, etc.)
rostree scan ~/dev --depth 3 # Scan specific directories
rostree scan --no-home # Skip home directory
rostree scan --no-system # Skip /opt/ros system installs
rostree scan --json # Output as JSON
rostree scan -v # Verbose: show packages in each workspace
rostree list¶
List known ROS 2 packages in the current environment.
rostree list # List all packages
rostree list --by-source # Group by source (System, Workspace, etc.)
rostree list -f nav2 # Only packages whose name contains "nav2"
rostree list -v # Show package paths
rostree list --json # Output as JSON
rostree list -s /extra/src # Add extra source directories
rostree tree¶
Show the dependency tree for a package.
rostree tree rclpy # Full tree (unlimited depth is fine now)
rostree tree rclpy -d 3 # Limit depth to 3 levels
rostree tree rclpy -r # Runtime-only (depend + exec_depend)
rostree tree rclpy -v # Include package descriptions
rostree tree rclpy --json # Output as JSON
rostree tree rclpy -s /src # Add extra source directories
A package that appears in several branches is expanded where it first appears;
elsewhere it is summarised as ↩ 5 already shown above: …. That is what keeps a
full-depth tree instant instead of exponential — see
Dependency trees.
rostree tree rclpy --expand-repeats # One line per back-reference
rostree tree rclpy --full # Re-expand every occurrence (can be huge)
rostree tree rclpy --full --max-nodes 5000
The tree goes to stdout and the summary line to stderr, so rostree tree rclpy > deps.txt
captures just the tree.
rostree why¶
Explain how one package ends up depending on another.
rostree why nav2_bringup rcutils # Shortest paths between the two
rostree why nav2_bringup rcutils -r # Runtime dependencies only
rostree why nav2_bringup rcutils -n 3 # At most 3 paths
rostree why nav2_bringup rcutils --json
Exits non-zero when there is no dependency path at all.
rostree rdeps¶
Reverse lookup: what would be affected if this package changed?
rostree rdeps rclcpp # Direct dependents
rostree rdeps rclcpp -t # Include indirect dependents
rostree rdeps rclcpp -w # Skip packages that belong to the ROS distro
rostree rdeps rclcpp --json
rostree check¶
Report dependency cycles and unresolved dependencies. Exits non-zero when it finds problems, so it can gate CI.
rostree check # Every workspace package
rostree check nav2_bringup # Specific roots
rostree check --ignore-system # Don't fail on names that look like rosdep keys
rostree check --junit report.xml # Also write a JUnit report for CI
rostree check --json
In CI:
--ignore-system is a guess from the name: an unresolved name with no underscore
(eigen, boost) is usually a rosdep key rather than a ROS package. But
rclcpp, tf2, urdf and xacro have no underscore either, so an unbuilt one
would be waved through too. Whatever the flag holds back is therefore always
listed — on stderr, and under "ignored" in --json — so a CI log shows what
was not checked.
rostree graph¶
Generate dependency graphs as an interactive HTML page, or as DOT (Graphviz) or Mermaid text. DOT can be rendered straight to PNG/SVG/PDF.
Interactive HTML — the one to reach for when you are actually trying to understand something, rather than paste a picture into a document:
rostree graph nav2_bringup -f html --open # write nav2_bringup.html and open it
rostree graph -w ~/ros2_ws -f html -o ws.html
rostree graph my_pkg -f html --only-workspace
The result is a single file with nothing external in it — no CDN, no fonts, no network at all. Mail it, commit it, or open it on a robot with no route out.
It does not draw the whole graph at once, because a full ROS workspace drawn all at once is a hairball nobody reads twice. Instead you are always looking at one package's neighbourhood:
| Click a package | re-centre the graph on it |
| Hover | light up everything upstream and downstream of it, dim the rest |
| Shift-click | pin a second package and list the shortest paths between the two — rostree why, drawn |
/ |
search; arrows and enter to jump |
d u b |
dependencies · dependents · both |
[ ] |
fewer or more hops |
f / r / t / ? |
fit · back to start · theme · help |
Packages are coloured by where they came from, using the same palette as the
TUI, so /opt/ros and your own workspace are distinguishable at a glance, and
unresolved names are drawn dashed. The current view lives in the URL, so a
focused view can be shared by copying the address.
# Single package - render to image (requires Graphviz)
rostree graph rclpy --render png # Creates rclpy.png
rostree graph rclpy --render svg --open # Create SVG and open it
rostree graph rclpy --render pdf -o out.pdf
# Single package - text output
rostree graph rclpy # DOT format to stdout
rostree graph rclpy -f mermaid # Mermaid format
rostree graph rclpy -f html -o d.html # Interactive, self-contained
rostree graph rclpy -o deps.dot # Write DOT to file
rostree graph rclpy -d 3 # Limit depth
# Entire workspace (current environment)
rostree graph --render png # Graph all non-system packages
rostree graph -d 2 --render svg # Limit depth for performance
# Specific workspace
rostree graph -w ~/ros2_ws --render png # Scan and graph workspace
rostree graph -w ~/ros2_ws -f mermaid # Mermaid format (text only)
# Options
rostree graph rclpy -r # Runtime-only dependencies
rostree graph rclpy --no-title # No title in graph
rostree graph rclpy --hide-missing # Omit unresolved dependencies
Dependencies that do not resolve to a package.xml (rosdep keys, packages that
are not built yet) are drawn dashed and grey rather than dropped. Dropping
them is what used to leave workspace graphs as a set of unconnected boxes. Pass
--hide-missing if you only want edges between packages you actually have.
-w/--workspace also puts that workspace on the search path, so it works on a
workspace you have not sourced.
Install a rendering backend for --render:
Option 1: Graphviz (best quality, system package)
Option 2: matplotlib (pure pip, no system deps)
If both are available, Graphviz is preferred for better layout quality.
Manual rendering (alternative):
# DOT → PNG
rostree graph rclpy -o deps.dot
dot -Tpng deps.dot -o deps.png
# Mermaid → view online
rostree graph rclpy -f mermaid | pbcopy # Copy to clipboard
# Paste at https://mermaid.live
Scoping what you look at¶
Every command that walks the dependency graph (tree, graph, why, rdeps,
check, diff) takes the same scope flags. On a sourced ROS 2 machine most of
what rostree can see belongs to the distro, so these are usually what you want:
rostree tree my_robot_bringup -w # ignore the ROS distro's packages
rostree tree my_robot_bringup --include 'nav2_*'
rostree tree my_robot_bringup --exclude '*_msgs' --exclude 'rosidl_*'
rostree graph --only-workspace --render png # graph just your own packages
-w/--only-workspacedrops the ROS distro's own packages — under/opt/ros, or wherever a source build or RoboStack env put them (see Package discovery).--include GLOBkeeps only matching package names; repeat for several globs.--exclude GLOBdrops matching names. Excludes win over includes.- Patterns are shell globs matched against the package name, and are case-sensitive.
A filtered-out package is neither shown nor followed, so anything reachable
only through it disappears too — that is what makes --only-workspace useful.
Because that hides real edges, every one of these commands says what was held
back: a line on stderr, and a "filtered" list in --json output.
rdeps is the one exception to "not followed", on purpose. It answers what
breaks if this changes, so it walks the full reverse graph and filters the
answer afterwards: excluding an intermediate package must not hide the dependents
behind it.
Which dependencies to follow¶
rostree tree rclcpp --dep-type runtime # depend + exec_depend (same as -r)
rostree tree rclcpp --dep-type build # depend + build_depend + build_export_depend
rostree tree rclcpp --dep-type test # depend + test_depend
rostree tree rclcpp --dep-type all # everything (the default)
rostree diff¶
What did this package gain, lose or bump?
# Compare two packages
rostree diff nav2_bringup nav2_route
# Compare a package against its own past
rostree diff my_robot_bringup --save deps.json
# ...rebuild, update, change a manifest...
rostree diff my_robot_bringup --against deps.json
Exits non-zero when anything moved, so it works as a drift check in CI. --json
gives added / removed / changed for scripting.
TUI (Terminal UI)¶
rostree # Launch the TUI
rostree tui nav2_bringup # Open straight into a package's tree
rostree tui --all-deps # Follow build and test dependencies too
Flow¶
- Welcome screen — the package scan starts immediately in the background and reports its count when done. Press Enter to continue, q to quit.
- Package list — every package, grouped by source. Press / and type to filter across all of them. Enter opens a package.
- Tree view — the dependency tree, with a details panel on the right.
Keys¶
| Key | Action |
|---|---|
| ? | Keyboard reference |
| / or f | Filter the package list (or search an open tree) |
| Enter | Open the selected package / re-root the tree on it |
| Esc or b | Leave the filter, then go back to the package list |
| ↑ ↓ | Move |
| n / N | Next / previous search match |
| d | Show or hide the details panel |
| v | Reverse view: what depends on this package |
| t | Toggle runtime-only vs all dependencies |
| e / c | Expand all / collapse all |
| a | Add an extra source path |
| r | Rescan packages |
| q | Quit |
Responsiveness¶
- Scanning and tree building both run on worker threads, so the UI never blocks.
- Tree rows are created as you expand them, so opening a package with thousands of transitive dependencies is instant.
- The package list is not truncated; use the filter to narrow it.
Details panel¶
For the selected node: version, description, direct dependency count, total
descendants, depth below this node, which source it came from, and its
package.xml path.
Python API¶
Everything the CLI can tell you, a script can ask for directly — the CLI is built
on these same functions. Everything exported from rostree.api follows semantic
versioning; anything under rostree.core is internal and may move.
from rostree.api import (
build_graph, build_tree, dependency_paths, dependency_versions,
diff_dependencies, get_index, reverse_dependencies, tree_stats,
FilterReport, PackageFilter,
)
Ask the questions the CLI answers¶
# rostree why: every shortest path from one package to another
dependency_paths("my_robot_bringup", "rcutils")
# [['my_robot_bringup', 'my_robot_control', 'rclcpp', 'statistics_msgs', 'rcutils'], ...]
# rostree rdeps --transitive: what breaks if this changes?
reverse_dependencies("my_robot_msgs", transitive=True)
# rostree diff: snapshot a package's dependency set, compare after a rebuild
before = dependency_versions(build_graph("my_robot_nav"), exclude=["my_robot_nav"])
# ... rebuild ...
after = dependency_versions(build_graph("my_robot_nav"), exclude=["my_robot_nav"])
diff = diff_dependencies(before, after)
if diff: # truthy when anything moved
print(diff.added, diff.removed, diff.changed)
Build the graph yourself¶
# The resolved DAG — linear in the number of packages, whatever the shape
graph = build_graph("nav2_bringup", dep_type="runtime")
graph.edges # {"nav2_bringup": ["nav2_common", ...], ...}
graph.packages # name -> PackageInfo, for every package that resolved
graph.missing # names that resolve to no package.xml
graph.truncated # names past max_depth: exist, but were not walked
graph.cycles() # [["a", "b", "a"], ...]
# A renderable tree: each package expanded once, repeats marked
root = build_tree("rclpy", max_depth=5)
tree_stats(root) # {'nodes': 770, 'packages': 164, 'repeats': 543, ...}
root.to_dict() # the same JSON `rostree tree --json` prints
Scope: the same knobs as the command line¶
Every function that walks the graph takes the same scope arguments:
report = FilterReport()
graph = build_graph(
"my_robot_bringup",
dep_type="build", # runtime | build | test | all
package_filter=PackageFilter(
include=("my_robot_*",), exclude=("*_msgs",), only_workspace=True
),
report=report, # what the filter removed
)
print(report.summary()) # "3 package(s) hidden by filters: ..."
A filtered-out package is neither returned nor followed. reverse_dependencies
is the one exception, as on the command line: it filters the answer, not the
walk, so excluding a package never hides the dependents behind it. An unknown
dep_type raises ValueError rather than quietly following everything.
runtime_only=True is the older spelling of dep_type="runtime" and still works.
Pass index=get_index() (or one you built) to reuse a single package scan across
many calls; otherwise a process-wide cached index is used.
Render it¶
from rostree.api import GraphView, to_dot, to_html, to_mermaid
from pathlib import Path
graph = build_graph("my_robot_bringup")
view = GraphView.from_graph(graph)
Path("deps.dot").write_text(to_dot(view), encoding="utf-8")
Path("deps.mmd").write_text(to_mermaid(view), encoding="utf-8")
# The interactive viewer. Pass the index so packages are coloured by source.
Path("deps.html").write_text(to_html(graph, index=get_index()), encoding="utf-8")
Write with an explicit encoding="utf-8": the viewer contains characters such
as → that the default codec on Windows cannot encode.
Discovery¶
from rostree.api import (
get_package_info, list_known_packages, list_known_packages_by_source, scan_workspaces,
)
list_known_packages() # {name: Path to package.xml}
list_known_packages_by_source() # {"System (/opt/ros/jazzy)": [...], "Source (...)": [...]}
get_package_info("rclpy") # PackageInfo: name, version, dependencies, ...
scan_workspaces() # [WorkspaceInfo(path, has_src, has_install, packages)]
index = get_index()
index.resolve("rclcpp") # Path to its package.xml, or None
index.get("rclcpp").kind # SourceKind.SYSTEM
index.workspace_names() # every package that is not the distro's
scan_workspaces(roots=None, max_depth=4, include_home=True, include_opt_ros=True)
looks in common locations (~/*_ws, ~/dev, /opt/ros/*) unless given roots,
and only reports a directory that contains a package or colcon's markers.
Deprecated¶
build_tree(include_buildtool=...)has never had an effect —buildtool_dependentries are build tooling and are not traversed. PassingTruenow raises aDeprecationWarning; the parameter goes in 2.0.