{"id":2818,"library":"treescope","title":"Treescope","description":"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.","status":"active","version":"0.1.10","language":"en","source_language":"en","source_url":"https://github.com/google-deepmind/treescope","tags":["visualization","pretty-printer","ipython","jupyter","machine-learning","jax","numpy","pytorch","debugger"],"install":[{"cmd":"pip install treescope","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for array handling.","package":"numpy","optional":false},{"reason":"Required for notebook integration and interactive rendering features.","package":"ipython","optional":true},{"reason":"Enables enhanced visualization for JAX arrays and PyTrees.","package":"jax","optional":true},{"reason":"Enables enhanced visualization for PyTorch tensors.","package":"torch","optional":true},{"reason":"Adds out-of-the-box support for Pydantic BaseModel visualization.","package":"pydantic","optional":true},{"reason":"Adds out-of-the-box support for Hydra/OmegaConf DictConfig/ListConfig visualization.","package":"omegaconf","optional":true}],"imports":[{"symbol":"treescope","correct":"import treescope"},{"note":"Used to explicitly render objects with Treescope, similar to `print`.","symbol":"show","correct":"treescope.show(...)"},{"note":"Used to display a value as an interactively foldable object.","symbol":"display","correct":"treescope.display(...)"},{"note":"Calling `basic_interactive_setup()` is crucial for Treescope to act as the default IPython renderer and enable automatic array visualization.","wrong":"import treescope # (without setup call)","symbol":"basic_interactive_setup","correct":"treescope.basic_interactive_setup()"}],"quickstart":{"code":"import treescope\nimport jax\nimport jax.numpy as jnp\nimport numpy as np\n\n# Enable Treescope as the default IPython renderer and auto-visualizers\ntreescope.basic_interactive_setup()\n\n# Define a nested data structure with arrays\nmy_data = {\n    \"model_config\": {\n        \"num_layers\": 4,\n        \"hidden_size\": 256,\n        \"activation\": \"relu\"\n    },\n    \"weights\": {\n        \"layer_0\": jnp.ones((16, 256)),\n        \"layer_1\": jnp.zeros((256, 128))\n    },\n    \"metadata\": [\n        \"training_started\",\n        \"epoch_1\",\n        {\"loss\": 0.123, \"accuracy\": 0.98, \"grad_norm\": np.array(0.005)}\n    ]\n}\n\n# In an IPython notebook, simply outputting the variable will use Treescope:\nmy_data\n\n# Or explicitly display it:\ntreescope.display(my_data)","lang":"python","description":"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."},"warnings":[{"fix":"Call `treescope.basic_interactive_setup()` at the beginning of your notebook session to enable Treescope as the default renderer and activate array autovisualization.","message":"Treescope'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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"While 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}