# How to Export a treelib Tree to a Dictionary: Complete Guide to `to_dict()`

> Export your treelib tree to a dictionary using the to_dict method. Learn to serialize tree structures into nested Python dictionaries with optional controls.

- Repository: [Xiaming Chen/treelib](https://github.com/caesar0301/treelib)
- Tags: how-to-guide
- Published: 2026-02-26

---

**Use the `Tree.to_dict()` method in treelib to serialize any tree structure into a nested Python dictionary, with optional parameters to control sorting, data inclusion, and subtree selection.**

The `treelib` library (maintained in the [caesar0301/treelib](https://github.com/caesar0301/treelib) repository) provides a robust `Tree` class for managing hierarchical data. When you need to export a treelib tree to a dictionary for JSON serialization, API responses, or data interchange, the built-in `to_dict()` method handles the conversion efficiently.

## Understanding the `Tree.to_dict()` Method

The `to_dict()` method performs a depth-first traversal of the tree (or breadth-first when sorting is enabled) and constructs a nested dictionary structure. Each node's tag becomes a key, with children stored under a `"children"` list.

### Method Signature and Parameters

Located in [`treelib/tree.py`](https://github.com/caesar0301/treelib/blob/main/treelib/tree.py) at lines 51-80, the method signature is:

```python
def to_dict(self, nid=None, key=None, sort=True, reverse=False, with_data=False)

```

| Parameter | Type | Description |
|-----------|------|-------------|
| `nid` | `Optional[str]` | Node identifier for the subtree root; defaults to the tree's root node. |
| `key` | `Optional[Callable]` | Function for sorting children (e.g., `lambda n: n.tag`). |
| `sort` | `bool` | Whether to sort children before exporting (default: `True`). |
| `reverse` | `bool` | Reverse the sort order (default: `False`). |
| `with_data` | `bool` | Include each node's `data` attribute in the output (default: `False`). |

### Source Implementation

The core logic resides in [[`treelib/tree.py`](https://github.com/caesar0301/treelib/blob/main/treelib/tree.py)](https://github.com/caesar0301/treelib/blob/master/treelib/tree.py). The method recursively processes nodes, building dictionaries that preserve the hierarchical relationships established by the tree structure.

## Basic Examples: Export a treelib Tree to a Dictionary

### Export Tree Structure Only

The simplest use case exports just the node tags and hierarchy:

```python
from treelib import Tree

tree = Tree()
tree.create_node("Root", "root")
tree.create_node("Child A", "a", parent="root")
tree.create_node("Child B", "b", parent="root")

# Export to dictionary

tree_dict = tree.to_dict()
print(tree_dict)

```

Output:

```python
{'Root': {'children': [{'Child A': {'children': []}}, 
                       {'Child B': {'children': []}}]}}

```

### Include Node Data Attributes

When nodes carry additional payload data, use `with_data=True` to preserve it:

```python
tree.create_node("Data Node", "data", parent="root",
                 data={"type": "important", "value": 42})

tree_dict_with_data = tree.to_dict(with_data=True)
print(tree_dict_with_data)

```

Output:

```python
{'Root': {'children': [...], 'data': None}, 
 'Data Node': {'children': [], 'data': {'type': 'important', 'value': 42}}}

```

### Export Specific Subtrees

To export only a portion of the tree, specify the starting node ID with `nid`:

```python
subtree_dict = tree.to_dict(nid="a")  # Export only Child A's descendants

print(subtree_dict)

```

This returns a dictionary rooted at "Child A", excluding siblings and ancestors.

## Advanced Configuration Options

### Sorting Children During Export

By default, `to_dict()` sorts children to ensure consistent output. Control this behavior with the `sort` and `reverse` parameters:

```python

# Alphabetical order (default)

sorted_dict = tree.to_dict(sort=True)

# Reverse alphabetical

reverse_dict = tree.to_dict(sort=True, reverse=True)

# Preserve insertion order (Python 3.7+)

unsorted_dict = tree.to_dict(sort=False)

```

### Custom Sort Keys

For complex sorting logic, pass a callable to the `key` parameter. This function receives a node object and should return a comparable value:

```python

# Sort by node creation time (if stored in data)

sorted_by_time = tree.to_dict(
    key=lambda node: node.data.get("timestamp", ""),
    sort=True
)

# Sort by identifier length, then alphabetically

sorted_complex = tree.to_dict(
    key=lambda node: (len(node.identifier), node.tag.lower()),
    sort=True
)

```

## Persisting and Reloading Tree Data

### Save to JSON File

The dictionary output is immediately compatible with JSON serialization:

```python
import json

with open("tree.json", "w", encoding="utf-8") as fp:
    json.dump(tree.to_dict(with_data=True), fp, ensure_ascii=False, indent=2)

```

This produces a human-readable JSON file that preserves the full tree structure and node data.

### Reconstruct Tree from Dictionary

While `treelib` provides `Tree.from_dict()` for direct reconstruction, you can also implement custom loaders for specific dictionary formats:

```python
from treelib import Tree

def dict_to_tree(d, parent=None, tree=None):
    """Recursively convert a to_dict() output back to a Tree."""
    if tree is None:
        tree = Tree()
    
    for tag, content in d.items():
        node_id = tag  # In production, use unique IDs

        node_data = content.get("data")
        
        tree.create_node(tag, node_id, parent=parent, data=node_data)
        
        for child in content.get("children", []):
            dict_to_tree(child, parent=node_id, tree=tree)
    
    return tree

# Usage

with open("tree.json") as fp:
    data = json.load(fp)

reconstructed = dict_to_tree(data)
reconstructed.show()

```

For standard use cases, prefer the built-in `Tree.from_dict()` method, which handles the format produced by `to_dict()` automatically.

## Summary

- **Use `Tree.to_dict()`** to export a treelib tree to a dictionary, located in [`treelib/tree.py`](https://github.com/caesar0301/treelib/blob/main/treelib/tree.py) at lines 51-80.
- **Control the export scope** with the `nid` parameter to export specific subtrees.
- **Preserve node data** by setting `with_data=True` to include the `data` attribute in the output.
- **Sort output consistently** using `sort`, `reverse`, and `key` parameters for ordered serialization.
- **Integrate with JSON** by passing the dictionary directly to `json.dump()` for persistent storage.
- **Reconstruct trees** using `Tree.from_dict()` or custom loaders that parse the nested structure.

## Frequently Asked Questions

### How do I export only a specific branch of a treelib tree to a dictionary?

Pass the node identifier to the `nid` parameter of `to_dict()`. For example, `tree.to_dict(nid="child_node_id")` exports only the subtree rooted at that node, excluding siblings and ancestors. This is useful when you need to serialize specific sections of large hierarchical datasets.

### Can I include custom data attached to nodes when exporting to a dictionary?

Yes, set the `with_data=True` parameter when calling `to_dict()`. By default, only the node tags and hierarchy are exported. When `with_data` is enabled, each dictionary entry includes a `"data"` key containing the node's associated data payload, making it suitable for complex object serialization.

### How do I maintain a specific order when exporting a treelib tree to a dictionary?

Use the `sort`, `reverse`, and `key` parameters to control ordering. Set `sort=True` (default) for alphabetical ordering by tag, `reverse=True` to invert the order, or provide a custom `key` function (e.g., `lambda n: n.data.get("priority")`) to sort by specific node attributes. Set `sort=False` to preserve insertion order.

### Is the dictionary format compatible with JSON serialization?

Yes, the output of `to_dict()` is immediately compatible with Python's `json` module. The method returns standard Python dictionaries, lists, and primitive types that `json.dump()` can serialize without modification. Use `with_data=True` if you need to ensure node data (which must itself be JSON-serializable) is included in the exported file.