Skip to main content
██████╗  ██████╗ ███████╗████████╗██████╗ ███████╗███████╗
██╔══██╗██╔═══██╗██╔════╝╚══██╔══╝██╔══██╗██╔════╝██╔════╝
██████╔╝██║   ██║███████╗   ██║   ██████╔╝█████╗  █████╗
██╔══██╗██║   ██║╚════██║   ██║   ██╔══██╗██╔══╝  ██╔══╝
██║  ██║╚██████╔╝███████║   ██║   ██║  ██║███████╗███████╗
╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝   ╚═╝  ╚═╝╚══════╝╚══════╝

CI codecov PyPI version PyPI downloads Python versions License

Explore your ROS 2 dependency graph — from the command line, in a TUI, or in your browser.

rostree demo

Full reel, 82 s · how it was captured

Docs: https://guilyx.github.io/rostree — 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

The graph, in your browser

rostree graph my_robot_bringup -f html --open

One self-contained file — no CDN, no fonts, no network at all — so it survives being mailed, committed next to a design doc, or opened on a robot with no route out.

It never draws the whole graph at once, because a workspace drawn all at once is a hairball nobody opens twice. You are always looking at one package's neighbourhood:

Click re-centre on that package
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
/ search; d u b for dependencies · dependents · both; [ ] for depth

rostree's interactive HTML dependency graph

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.

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.

Measured on a 146-package workspace (122 installed + a 24-package source overlay), rostree tree my_robot_bringup -r:

depth 0.2.2 now
5 1,876 lines / 0.43 s 276 lines / 0.20 s
6 6,258 lines / 1.18 s 253 lines / 0.18 s
7 16,623 lines / 3.04 s 252 lines / 0.19 s
no depth limit (the default) 58,002 lines / 10.29 s 251 lines / 0.21 s

Nothing is hidden: every edge is still shown, once. --full restores the fully expanded tree if you want it. (What is real in these numbers.)

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 check --junit report.xml   # ...as a JUnit report for CI dashboards

rostree diff nav2_bringup nav2_route        # What differs between two packages?
rostree diff my_pkg --save deps.json        # Snapshot now...
rostree diff my_pkg --against deps.json     # ...and catch drift after a rebuild

rostree graph rclcpp -f html --open     # Interactive, one self-contained file
rostree graph rclcpp --render png       # PNG via Graphviz
rostree graph -w ~/ros2_ws -f html      # Whole workspace, explorable
rostree graph rclcpp -f mermaid         # Mermaid text

Scope: most of what you can see is not yours

On a sourced machine most packages belong to the distro. Every command that walks the graph takes the same filters:

rostree tree my_robot_bringup -w                 # ignore the ROS distro itself
rostree tree my_robot_bringup --include 'nav2_*'
rostree tree my_robot_bringup --exclude '*_msgs' --exclude 'rosidl_*'
rostree tree my_robot_bringup --dep-type build   # runtime · build · test · all

A filtered package is neither shown nor followed, so anything reachable only through it goes too. Commands report what they held back rather than passing a smaller tree off as the whole truth.

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.

rostree TUI showing a dependency tree

rostree TUI package list, grouped by source rostree TUI reverse dependency view

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

Build on it

rostree is meant to be built on. Build on rostree walks through the layers and four complete tools that use them — an architecture rule for CI, a ripple report, a dependency lock and a CSV export — all in examples/ and all run by the test suite. The algorithms explains each algorithm underneath, from the question it answers to the code that answers it.

Stability

From 1.0, the CLI commands and their flags and the names exported from rostree.api follow semantic versioning: no incompatible changes without a 2.0. Anything under rostree.core is internal and may move.

The exact text and layout rostree prints is not covered — output is for people. Pin --json if you are parsing it.

One thing worth knowing before you rely on it: the test suite runs entirely on generated fixtures and has never been exercised against a real ROS 2 install. The <ws>/install/src bug fixed in 0.3.0 had shipped in every release before it for exactly that reason. Running against a ros:jazzy container is the top roadmap item. 1.0 means the interface has settled, not that every layout in the wild is covered — please open an issue if yours is not.

Contributing

Bug reports, ideas, docs fixes and code are all welcome — see CONTRIBUTING.md. The single most useful thing you can send is a workspace report: how rostree did on a real workspace, right or wrong. Everyone taking part follows the Code of Conduct; security issues go through SECURITY.md, not a public issue.

Citing

We intend to publish rostree as a software paper — the plan is in docs/publication.md. Until then, cite the software: GitHub's Cite this repository button reads CITATION.cff. Please include the version you used.

Metadata

Release files for rostree 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rostree 1.1.0
File Size Uploaded Provenance Actions
rostree-1.1.0.tar.gz 74.2 kB With provenance Details for rostree-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rostree 1.1.0
File Interpreter ABI Platform Actions
rostree-1.1.0-py3-none-any.whl Python 3 none any Details for rostree-1.1.0-py3-none-any.whl

Total release size: 157.8 kB

Release files / rostree-1.1.0.tar.gz

Download URL rostree-1.1.0.tar.gz
Size 74.2 kB
Tags Source
SHA-256 checksum
How to use checksums
4d6666920934414d7151a264680f7d07b6613fa9bc3bff5ce6d27b875e19c5f0
BLAKE2b-256 checksum
How to use checksums
37dc999b9792a0e7dbe2b4ed89a46d7f1b3ff62aa5ecef7cacf34df4d1c8f866
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / rostree-1.1.0-py3-none-any.whl

Download URL rostree-1.1.0-py3-none-any.whl
Size 83.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f5010be93c285d483e8e95aba6a54730e0b8bf9a5c604e671ec15c01e9c980bc
BLAKE2b-256 checksum
How to use checksums
8967fb2c2032d5cff0838a9b424821f9f136bdc6c5e9690a0c1c1a64b65152ea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Security for rostree 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for rostree-1.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page