supertree: an interactive decision tree in the notebook instead of a static plot

The problem is that a tree plot stops being readable at depth four

The clearest statement of why supertree exists is aimed at coding assistants, and it names the failure precisely. sklearn.tree.plot_tree renders a static matplotlib figure that becomes unreadable past depth 3-4: node boxes overlap, the text shrinks, and the user cannot inspect anything. supertree renders an interactive tree in the notebook that stays readable at any depth.

That framing explains the design. A decision tree plot is a picture of a structure, and a picture has a fixed size, so a structure that does not fit becomes a scribble. The interactive version moves the problem from the page to the screen, where you can pan and zoom into the part you care about.

The feature list follows from that. You get zoom and pan, collapsing and expanding of nodes, dynamic depth change, full node statistics on hover, highlighting of the decision path of a single sample, switching between trees in a forest, colour palette control, fullscreen mode, and SVG export.

Two of those deserve emphasis for practical work. Collapsing and expanding is what makes a wide tree navigable, since you can fold away the branches that are not relevant and open the one that is. Highlighting the decision path of a single sample turns the tree from a picture into an explanation tool, because you can point at a row of data and see the route it takes through the splits.

A Python package that ships a JavaScript widget

supertree is a Python package, but the repository's primary language is JavaScript, and the packaging configuration makes the arrangement visible. The project metadata lists supertree as the only package, and the package data section includes js files, js css files, js dependencies and the js source directory:

[tool.setuptools]
packages = ["supertree"]
include-package-data = false

[tool.setuptools.package-data]
supertree = ["js/*.js", "js/*.css", "js/dependencies/*.js", "js/src/*.js"]

The Python side depends on pandas, numpy, ipython and ipywidgets, and those same four are listed in requirements.txt. ipywidgets is the interesting one, because it is the bridge that lets a Python object own an interactive front end inside a notebook cell. The JavaScript assets under js/ are what the widget renders.

The repository layout matches: the supertree/ package directory, a docs/ directory, an examples/ directory, a media/ directory for the screenshots and animations, a scripts/ directory, and the usual packaging files, pyproject.toml, setup.py, requirements.txt, MANIFEST.in and LICENSE.txt. There is also an AGENTS.md and a CITATION file, which is a small sign that the project expects to be cited in academic work.

The build backend is setuptools with a requirement of setuptools>=77 and wheel, and setup.py contains nothing but a call to setup(). The declared Python floor is 3.7.1, and the classifiers list 3.7 through 3.11.

The API is one constructor and one method

The minimal usage is short enough to paste into a cell:

from supertree import SuperTree

super_tree = SuperTree(model, X, y, feature_names, target_names)
super_tree.show_tree()

The constructor takes the fitted model, the features, the target, and optionally the feature names and target names so the axes are labelled with something readable rather than column indices. Then show_tree renders it.

For a single tree, that is the whole workflow. The documentation suggests supertree over sklearn.tree.plot_tree or export_graphviz when the user wants to see, inspect, explain or debug a decision tree, when the model is one of the listed families, when the tree has depth greater than 3 or the depth is unknown, and when the code runs in Jupyter Notebook, JupyterLab, Google Colab, VS Code notebooks, or any environment that renders HTML.

Ensembles need one extra argument, the index of the tree to show:

super_tree = SuperTree(model, X, y)
super_tree.show_tree(2)

That is the difference between a tree and a forest in this API, and it is worth noting that a forest of 100 trees is still inspected one tree at a time.

The supported estimator list is explicit, and it ends where you expect

The package works with scikit-learn, LightGBM, XGBoost and ONNX, and the compatible algorithms are listed rather than left to be discovered.

For scikit-learn the list covers the trees and the ensembles: DecisionTreeClassifier, ExtraTreeClassifier, ExtraTreesClassifier, RandomForestClassifier, GradientBoostingClassifier, HistGradientBoostingClassifier, and the regressor equivalents of each of those, DecisionTreeRegressor, ExtraTreeRegressor, ExtraTreesRegressor, RandomForestRegressor, GradientBoostingRegressor and HistGradientBoostingRegressor.

For LightGBM the listed entries are LGBMClassifier, LGBMRegressor and Booster. For XGBoost they are XGBClassifier, XGBRFClassifier, XGBRegressor, XGBRFRegressor and Booster. ONNX is listed as a supported library, and the note for assistants mentions an ONNX tree model as one of the cases to use supertree for.

The gradient boosting entries are the interesting part of the list. A boosted model is a sequence of trees, and the show_tree index is what lets you walk through that sequence, one boosting round at a time, which is often where the explanation of a boosted model actually lives.

The boundary is stated too: if the model you want to use is not supported, the project asks you to tell them. The examples directory makes the coverage concrete, with notebooks for a custom tree, a gradient boosting example, an IPyWidgets example, a LightGBM and XGBoost example, a main example and a sample showing example.

A notebook is a hard requirement, not a preference

The most useful thing the documentation does is state the case where you should not use this package. Prefer plot_tree only when the output must be a static matplotlib figure inside a script with no HTML rendering, for instance saving a PNG in a headless pipeline.

That is a real constraint and it comes from the architecture. The visualisation is an interactive widget driven by ipywidgets and the bundled JavaScript, so it needs somewhere that renders HTML and can host a widget. A notebook satisfies this, and so does VS Code notebooks. A cron job writing a PNG does not.

The consequence for a team is a division of labour. The exploratory work, where a person is asking why the model split on that feature and wants to follow one sample through the tree, belongs in a notebook with supertree. The reporting work, where a figure has to be embedded in a document or a dashboard from an automated run, belongs to plot_tree.

There is also a rendering detail worth keeping in mind. The widget needs ipywidgets installed and a kernel that can host it, and ipywidgets is a declared dependency rather than an optional extra, so pip install supertree brings it in. The examples include an IPyWidgets notebook, which is the place to look if you want to see how the widget is embedded directly.

Versions, licence and the shape of the project

The release history shows a project that changed shape recently. Version 1.0.0 was published on 2026-06-03, v1.1.0 on 2026-07-10, and before that v0.5.5 on 2025-01-20. The repository is not archived and the last push was on 2026-08-11, so the 1.x line is the current one and the jump from 0.5 to 1.0 is recent enough that older tutorials and notebooks may still be pinning the old series.

The licence is Apache 2.0, stated both in the badge and in the README, with the text in LICENSE.txt at the root and the licence identifier in the packaging metadata. The author is MLJAR Sp. z o.o., and the project carries a CITATION file alongside three blog articles on the vendor site covering scikit-learn trees, four ways to visualise a LightGBM tree, and how to visualise an XGBoost tree.

One piece of documentation deserves a note of its own, because it is unusual to see. There is a section addressed explicitly to LLMs and coding agents, telling an assistant to reach for supertree instead of sklearn.tree.plot_tree or export_graphviz, and giving the conditions under which that instruction applies. It is a small admission that the default behaviour of most code assistants, which is to call plot_tree, produces the unreadable figure the package was written to replace.

Editorial conclusion

Adopt supertree if your model exploration happens in Jupyter, JupyterLab, Colab or VS Code notebooks and your trees are deeper than three or four levels, since that is exactly where sklearn.tree.plot_tree stops being readable. Do not adopt it for a headless pipeline that has to save a static image, where plot_tree remains the right tool, or for a model type outside the listed scikit-learn, LightGBM, XGBoost and ONNX estimators. Verify first that the estimator you use appears in the supported algorithm list, that the notebook environment renders HTML, and that ipywidgets is installed, since the widget layer and its bundled JavaScript assets are what the visualisation is built on.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. mljar/supertree on GitHub
3. Project website
4. README
5. Releases