nutree

library1.2.0pypypi✓ verified 22d ago

Nutree is a Python library for tree data structures with an intuitive, yet powerful, API. It allows handling of arbitrary objects in a hierarchical structure, offering features like navigation, searching, filtering, serialization to JSON and DOT, diffing, and typed child nodes. The library is actively maintained with regular releases, currently at version 1.1.0.

data serialization

pip install nutree

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · NUTREE

nutree

datapythonv1.2.0

Install

2.1s avg

Import

287ms

Disk

23MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.0 · 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

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 0.301s · 24.9MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 2.1s · import 0.273s · 25MB

23MB installed

● package 23MB

Code

Verified usage

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

Tree

✓ from nutree import Tree

Node

✓ from nutree import Node

This example demonstrates how to create a tree, add nodes using string data and arbitrary objects, chain `add` calls for easy construction, and pretty print the tree structure. It also shows how to access nodes by their name.

from nutree import Tree # Create a new tree tree = Tree("Root") # Add nodes in a chained fashion chapter1 = tree.add("Chapter 1") chapter1.add("Section 1.1") chapter1.add("Section 1.2") # Go up to the root and add another branch chapter2 = tree.add("Chapter 2") chapter2.add("Section 2.1").add("Subsection 2.1.1") # Pretty print the tree tree.print() # Access a node by name section_1_1 = tree["Section 1.1"] assert section_1_1.name == "Section 1.1" # Add an arbitrary object as data to a node class Task: def __init__(self, name, priority): self.name = name self.priority = priority def __str__(self): return f"Task({self.name}, P:{self.priority})" task_node = chapter1.add(Task("Review Draft", 1)) assert isinstance(task_node.data, Task)

Debug

Known issues

gotchaThe Python `nutree` library is distinct from the JavaScript `nut-tree/nut.js` project. Ensure you are consulting the correct documentation and examples for the Python package.

fix

Verify that documentation and examples explicitly reference 'nutree' (Python) or the PyPI/GitHub project for this library.

affects: All

gotchaAdvanced features like graph visualization (DOT, Mermaid) require installing optional dependencies using `pip install "nutree[graph]"` or `pip install "nutree[all]"`.

fix

If you need graph features, install with the appropriate extra, e.g., `pip install "nutree[graph]"`.

affects: All

gotchaNutree nodes can wrap arbitrary objects, and the library handles multiple references to the same object ('clones') distinctly within the tree. Node lookup can be done by name, object reference, or a generated `data_id`, which might differ from direct Python object identity comparisons if not handled carefully.

fix

Be aware of how `nutree` handles object references and identity within the tree structure. Use the library's methods for searching and comparing nodes to ensure expected behavior, especially when an object is part of the tree multiple times.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'nutree'

The 'nutree' library is not installed in your Python environment or the environment where your script is being run.

fix

Install the library using pip: `pip install nutree`

TypeError: unhashable type: 'dict'

You are attempting to add a mutable, unhashable Python object (like a dictionary) directly to a `nutree` tree's node, and 'nutree' cannot implicitly generate a unique `data_id` for it.

fix

Provide an explicit `data_id` when adding the object, or wrap the dictionary in `nutree.DictWrapper`. Example: `node.add({'key': 'value'}, data_id='unique_id')` or `from nutree import DictWrapper; node.add(DictWrapper({'key': 'value'}))`

ImportError: cannot import name 'NodeTree' from 'nutree'

You are trying to import a class or object named 'NodeTree' which does not exist or is not directly exposed by the 'nutree' library.

fix

Import the correct core components, typically `Tree` and `Node`: `from nutree import Tree, Node`

Upgrade

Version history

1.2.0latest on PyPI · released Aug 15, 2026

Audit

Dependencies

graphvizoptionalRequired for generating DOT files and Graphviz diagrams when using the 'graph' extra.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/mar10/nutree ↗

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

docshttps://nutree.readthedocs.io/ ↗