treescope

library0.1.10pypypi✓ verified 25d ago

Treescope is an interactive HTML pretty-printer and N-dimensional array ("tensor") visualizer, designed for machine learning and neural networks research in IPython notebooks. It serves as a drop-in replacement for the standard IPython/Colab renderer, enhancing output with features like expandable/collapsible subtrees, embedded faceted visualizations of arbitrary-dimensional arrays, and color-coding for model structures. It supports inspecting data from libraries such as JAX, NumPy, PyTorch, Equinox, Flax NNX, and Penzai. Maintained by Google DeepMind, the current version is 0.1.10.

ai-ml observability

pip install treescope

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TREESCOPE

treescope

ai-mlpythonv0.1.10

Install

3.5s avg

Import

459ms

Disk

89MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.1.10 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 3.7s

py 3.11

✓ —

✓ 3.5s

py 3.12

✓ —

✓ 3.5s

py 3.13

✓ —

✓ 3.4s

py 3.9

✕ build_error

89MB installed

● package 89MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

treescope

✓ import treescope

show

✓ treescope.show(...)

Used to explicitly render objects with Treescope, similar to `print`.

display

✓ treescope.display(...)

Used to display a value as an interactively foldable object.

basic_interactive_setup

✓ treescope.basic_interactive_setup()

✗ import treescope # (without setup call)

Calling `basic_interactive_setup()` is crucial for Treescope to act as the default IPython renderer and enable automatic array visualization.

This quickstart demonstrates how to enable Treescope as the default renderer in an IPython/Colab environment and visualize a complex, nested data structure containing both JAX and NumPy arrays. After `basic_interactive_setup()`, simply outputting a variable in a notebook cell will automatically trigger Treescope's rich, interactive HTML visualization.

import treescope import jax import jax.numpy as jnp import numpy as np # Enable Treescope as the default IPython renderer and auto-visualizers treescope.basic_interactive_setup() # Define a nested data structure with arrays my_data = { "model_config": { "num_layers": 4, "hidden_size": 256, "activation": "relu" }, "weights": { "layer_0": jnp.ones((16, 256)), "layer_1": jnp.zeros((256, 128)) }, "metadata": [ "training_started", "epoch_1", {"loss": 0.123, "accuracy": 0.98, "grad_norm": np.array(0.005)} ] } # In an IPython notebook, simply outputting the variable will use Treescope: my_data # Or explicitly display it: treescope.display(my_data)

Debug

Known issues

gotchaTreescope's rich HTML output and automatic rendering features are only active in IPython/Colab notebooks after `treescope.basic_interactive_setup()` or manual registration. Without this setup, objects will revert to standard `repr()` output.

fix

Call `treescope.basic_interactive_setup()` at the beginning of your notebook session to enable Treescope as the default renderer and activate array autovisualization.

affects: All versions

gotchaThe full interactive power of Treescope (e.g., expanding/collapsing subtrees, 'roundtrip mode' with the 'r' key for qualified names, 'copy path' buttons) requires direct user interaction within the rendered HTML output in an IPython environment, which might not be immediately obvious to new users.

fix

Encourage users to click on rendered objects and experiment with keyboard shortcuts (like 'r') within the IPython output to unlock interactive exploration. Refer to official documentation for interactive features.

affects: All versions

gotchaWhile Treescope supports common Python types and popular ML libraries, visualizing highly custom or complex data structures may require implementing custom `treescope` rendering logic to achieve optimal interactive display.

fix

For bespoke data structures, consult the 'Customizing Treescope' section of the official documentation to learn how to define custom visualizers or `__treescope_repr__` methods.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'treescope'

The 'treescope' package has not been installed in the current Python environment.

fix

Run `pip install treescope` in your terminal or notebook. For Colab, use `pip install 'treescope[colab]'`.

NameError: name 'treescope' is not defined

The 'treescope' library has not been imported before attempting to use its attributes or functions.

fix

Add `import treescope` at the beginning of your script or notebook.

ImportError: cannot import name 'active' from 'treescope'

The user is attempting to import 'active' as a submodule or function directly from the 'treescope' package, but 'active' is a boolean attribute of the 'treescope' module.

fix

Import the 'treescope' module and then set its 'active' attribute: `import treescope; treescope.active = True`.

TypeError: display() missing 1 required positional argument: 'value'

The `treescope.display()` function was called without providing the object that needs to be visualized.

fix

Pass the object you wish to display as an argument, for example: `treescope.display(my_variable)`.

Upgrade

Version history

0.1.10latest on PyPI · released Aug 8, 2025

Audit

Dependencies

numpyrequiredCore dependency for array handling.

ipythonoptionalRequired for notebook integration and interactive rendering features.

jaxoptionalEnables enhanced visualization for JAX arrays and PyTrees.

torchoptionalEnables enhanced visualization for PyTorch tensors.

pydanticoptionalAdds out-of-the-box support for Pydantic BaseModel visualization.

omegaconfoptionalAdds out-of-the-box support for Hydra/OmegaConf DictConfig/ListConfig visualization.

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/google-deepmind/treescope ↗

packagehttps://pypi.org/project/treescope/ ↗

homepagehttps://treescope.readthedocs.io ↗