Treescope: An Interactive HTML Pretty-Printer for ML Notebooks

What Treescope Replaces, and for Whom

The default IPython and Colab renderer prints a nested Python object as a wall of repr text. For a dictionary of model parameters, that means hundreds of lines of array literals with no structure you can collapse and no indication of which submodules share weights. Treescope's stated purpose is to replace that renderer with an interactive HTML view. The README frames it as "a drop-in replacement for the standard IPython/Colab renderer."

The audience is narrow and clearly stated: machine learning and neural network researchers working in notebooks. Treescope was originally built as the pretty-printer for the Penzai neural network library, and the README lists Equinox, Flax NNX and PyTorch as supported model libraries, plus plain JAX and NumPy code. If you are debugging a transformer's parameter tree, or checking whether two branches of a model actually share an array, this is the intended use. If you are writing a data pipeline or a CLI tool, nothing here is aimed at you.

The Rendering Mechanism: HTML Trees, Faceted Arrays, Roundtrip Mode

Treescope does not print text. It produces an HTML rendering of the object graph, and the interactivity lives in that output. The README lists the concrete behaviors: expanding and collapsing subtrees, embedding faceted visualizations of arbitrary-dimensional arrays directly in the rendering, color-coding parts of neural network models to emphasize shared structure, and inserting copy-path buttons for any node.

The array visualization is the piece with the most engineering behind it. Rather than showing a tensor as a nested list, Treescope embeds a faceted view so you can see shape and value distribution at a glance. This is the feature that is hardest to replicate with a custom repr, and it is the reason the project describes itself as an "N-dimensional array ('tensor') visualizer" as well as a pretty-printer.

There is also a roundtrip mode: click a rendered object and press the r key, and qualified names are added to every type in the visualization. That is a small feature with a real use case, since the difference between two similar-looking containers is often only visible in their fully qualified type names.

The extension point is a customization hook: the README says you can customize the visualization strategy to support your own data structures. That matters because Treescope has to decide how to render an object it has never seen, and the default strategy for unknown types is necessarily conservative. The documentation site at treescope.readthedocs.io is where the customization API is described; the README itself does not spell out the interface.

Getting It Running: Four Lines and a Config Key

Installation is a single pip command:

pip install treescope

Then, in a notebook, import treescope. To render one object, the README gives treescope.show, described as being like print but producing a rich interactive output. To make it the default for the whole session, run treescope.register_as_default().

Array visualization is a separate switch. The README shows treescope.active_autovisualizer.set_globally(treescope.ArrayAutovisualizer()) to turn it on. The combined setup is one call:

treescope.basic_interactive_setup(autovisualize_arrays=True)

That single call is the recommended path and does both jobs. There is one configuration key worth knowing about: abbreviation_threshold. The README notes that if Treescope's output is too verbose, or if your terminal wraps lines, you can pass abbreviation_threshold=1 (or another value) to basic_interactive_setup so collapsed objects are abbreviated at a given depth. The same setting can be overridden directly on treescope.abbreviation_threshold using .set_globally or .set_scoped, which gives you a session-wide default and a context-local override. The scoped variant is the interesting one: you can raise verbosity for one debugging cell without changing the global setting.

Where It Breaks Down

The first limitation is structural, not a bug. Treescope renders to HTML widgets. The README's entire getting-started path assumes an IPython notebook, and the interactive features (clicking the expand arrows, pressing r, holding shift to scroll horizontally) only make sense in a live widget. Anything that captures text output, such as a log file, a CI job, or a terminal session, gets none of this. If your debugging happens in scripts, Treescope is the wrong tool and the README does not pretend otherwise.

The second is version maturity. The most recent release listed is v0.1.10, from August 2025, following v0.1.9 and v0.1.8 in the first half of 2025. A 0.1.x line means the maintainers have not committed to API stability. Code that calls treescope.register_as_default() or the autovisualizer is small enough that breakage would be cheap to fix, but anything built on the customization API for your own types carries more risk.

The third is verbosity, which the project itself acknowledges. The README's tip about abbreviation_threshold exists because deep object trees can produce output that is hard to read, and the default depth may not match yours. A parameter dictionary with many small arrays is exactly the case where collapsing helps and where the default may still be too noisy.

One thing the supplied material does not establish: how Treescope behaves on very large tensors, or whether the faceted visualization downsamples. There is no stated size limit in the README, and I am not going to guess at one. Test it on your own shapes before relying on it for a multi-gigabyte activation.

Compared with rich, the General-Purpose Option

The obvious alternative for notebook rendering is rich, which is not ML-specific. Rich renders tracebacks, tables, progress bars and arbitrary Python objects, and it works in terminals as well as notebooks. The difference in approach is the target: rich aims for a consistent presentation layer across terminal and notebook, so its object rendering is a generic repr replacement with optional __rich_repr__ hooks. Treescope aims at one domain and goes deeper inside it.

Concretely, rich has no built-in notion of an N-dimensional array. You would write a custom renderable to get a faceted tensor view, and you would be writing it yourself. Rich also has no equivalent of Treescope's shared-structure color coding, which depends on understanding model trees. On the other side, rich renders to the terminal, and Treescope does not. If your work spans notebooks and command-line tools, rich covers both with one dependency; Treescope covers one of them well.

A second, less comparable option is to write your own repr. That is what many teams do, and it is fine until you want collapsible subtrees and array facets, at which point you are rebuilding Treescope's HTML layer. The honest framing is that Treescope is worth adopting when its specific features (collapse, array facets, shared-structure coloring) are what you need, and not worth adopting as a general print replacement.

Maintenance, Versions and the Apache-2.0 Terms

Treescope is licensed under Apache-2.0 and the repository is not archived, with a last push in June 2026. The release cadence visible in the supplied material is irregular: v0.1.8 in January 2025, v0.1.9 in February 2025, then v0.1.10 in August 2025. That is not a project shipping weekly, and it is not abandoned either.

The maintenance cost for a user is low if you stay on the documented path. Four calls (show, register_as_default, the autovisualizer setter, and basic_interactive_setup) cover nearly everything the README describes. The cost rises if you write a custom visualization strategy for your own types, because that code tracks an API the maintainers have not frozen at 1.0. Pinning treescope in your requirements file and reading the release notes before upgrading is the practical posture.

On licensing: Apache-2.0 permits commercial and internal use and includes a patent grant, which matters for a tool that may end up inside a company's research stack. It also requires that you preserve notices and state changes if you redistribute modified versions. The README carries a disclaimer that this is not an officially supported Google product, which is worth reading literally: the repository lives under the google-deepmind organization, but the support commitment is the maintainers', not Google's. This is a description of the licence text, not legal advice; check the full Apache-2.0 terms and your own counsel if you plan to redistribute.

Who Should Adopt Treescope, and What to Check First

Adopt it if your debugging loop runs inside IPython or Colab and your objects are nested model trees or arrays. The combination of collapsible subtrees, embedded array facets, shared-structure coloring and copy-path buttons addresses a specific annoyance that generic printers do not, and the setup is genuinely one call. The fact that it supports PyTorch, Equinox, Flax NNX, JAX and NumPy means you are not locked into Penzai to get the rendering, even though Penzai is where it started.

Do not adopt it as a general-purpose replacement for print or rich. It has no terminal story, and the version number says the API is still moving.

Before you wire it into a shared notebook template, verify two things locally. First, run treescope.register_as_default() alongside whatever else in your environment touches the IPython display formatter, since two libraries claiming the default renderer is a conflict the README does not address. Second, render one of your largest real tensors with the autovisualizer enabled and check that the faceted output is still readable at that size, because the README states no limit and I have not measured one. If both pass, the remaining cost is a pinned dependency and an occasional release-note read.

Editorial conclusion

Adopt Treescope if you spend your day inspecting nested parameter dictionaries, PyTorch modules, Equinox or Flax NNX models inside IPython or Colab, and you can tolerate a 0.1.x API. Do not adopt it for batch scripts, CI logs, or terminal output: the renderings are HTML widgets, and the README offers no non-notebook path. Before committing, verify two things in your own environment: that treescope.register_as_default() coexists with whatever else overrides the IPython display formatter, and that the array autovisualizer's thresholds suit your tensor sizes. Pin the version, because the jump from v0.1.9 to v0.1.10 shows the surface still moves.

Official sources

1. google-deepmind/treescope on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases