# How to Add a Root Node in treelib: Methods and Best Practices

> Learn how to add a root node in treelib using create_node or add_node without a parent. Discover best practices and avoid MultipleRootError in your Python tree structures.

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

---

**You add a root node in treelib by calling `create_node()` or `add_node()` without specifying a `parent` parameter, which automatically designates the first node as the root; attempting to add a second root raises a `MultipleRootError`.**

The treelib library provides a pure Python implementation for creating and manipulating tree data structures. Understanding how to properly add a root node in treelib is essential because the `Tree` class enforces a strict single-root hierarchy that governs all subsequent node operations.

## How treelib Handles Root Node Creation

The `Tree` class in [`treelib/tree.py`](https://github.com/caesar0301/treelib/blob/main/treelib/tree.py) maintains exactly one root identifier and validates all node insertions against this constraint. When you add a node without specifying a parent, the library checks whether a root already exists before assigning root status to the new node.

### The Validation Logic in `add_node()`

According to the treelib source code, the `add_node()` method contains the core validation logic that prevents multiple roots:

```python

# treelib/tree.py – add_node implementation (excerpt)

pid = parent.identifier if isinstance(parent, self.node_class) else parent

if pid is None:                         # ← no parent supplied

    if self.root is not None:
        raise MultipleRootError("A tree takes one root merely.")
    else:
        self.root = node.identifier      # ← node becomes the root

```

This implementation ensures that **only one root node can exist** in the tree structure. The `create_node()` method internally calls `add_node()`, passing the newly created `Node` object without a parent parameter when no parent is specified.

## Methods to Add a Root Node in treelib

You can establish a root node using two primary approaches, both leveraging the automatic root detection logic in the `Tree` class.

### Using `create_node()` (Recommended)

The `create_node()` method is the most common way to add a root node in treelib. When you omit the `parent` parameter on an empty tree, the method automatically designates the new node as the root:

```python
from treelib import Tree

tree = Tree()

# No parent specified → becomes the root

tree.create_node(tag="World", identifier="world")
print("Root identifier:", tree.root)   # Output: world

tree.show()

# └── World

```

### Using `add_node()` with a Pre-created Node

For scenarios requiring explicit `Node` object construction before tree insertion, use the `add_node()` method. Pass the `Node` instance without a parent parameter to establish it as the root:

```python
from treelib import Tree, Node

tree = Tree()
root_node = Node(tag="Universe", identifier="universe")

# Pass node without parent → becomes the root

tree.add_node(root_node)
print("Root identifier:", tree.root)   # Output: universe

```

## Error Handling: Preventing Multiple Roots

The treelib library strictly enforces single-root architecture. Attempting to add a second node without specifying a parent raises a `MultipleRootError`:

```python
from treelib import Tree

tree = Tree()
tree.create_node("First Root", "root1")

try:
    # This will raise an error

    tree.create_node("Second Root", "root2")
except Exception as e:
    print("Error:", e)  # Output: MultipleRootError: A tree takes one root merely.

```

To add subsequent nodes, you must specify an existing node identifier as the `parent` parameter:

```python

# Correct way to add child nodes

tree.create_node("Child Node", "child1", parent="root1")

```

## Summary

- **Single root enforcement**: The `Tree` class in [`treelib/tree.py`](https://github.com/caesar0301/treelib/blob/main/treelib/tree.py) strictly allows only one root node per tree instance.
- **Automatic root creation**: Call `create_node()` or `add_node()` without a `parent` parameter to establish the first node as the root.
- **Error prevention**: Attempting to add a second root raises `MultipleRootError`; always specify `parent` for subsequent nodes.
- **Implementation detail**: The root validation logic resides in the `add_node()` method, which checks `if pid is None` before assigning `self.root`.

## Frequently Asked Questions

### Can a treelib tree have multiple root nodes?

No, a treelib tree cannot have multiple root nodes. The library enforces a single-root hierarchy through the `MultipleRootError` exception, which triggers when you attempt to add a second node without specifying a parent. This design ensures the tree maintains a proper hierarchical structure with exactly one entry point.

### What happens if I don't specify an identifier when creating a root node?

If you omit the `identifier` parameter in `create_node()`, treelib automatically generates a unique identifier using Python's `uuid` module. The root node will still be established correctly, but you should specify explicit identifiers if you need predictable references for adding child nodes later.

### How do I replace an existing root node in treelib?

To replace a root node, you must first remove the existing root using `tree.remove_node(tree.root)`, which deletes the entire subtree, or use `tree.move_node()` to reposition the current root as a child of a new node. There is no direct "replace root" method because the library maintains the invariant that a tree must always have exactly one root or be empty.

### Is the root node automatically selected when calling create_node() on an empty tree?

Yes, when you call `create_node()` on an empty tree without specifying a `parent` parameter, the method automatically designates that node as the root. This behavior is handled internally by the `add_node()` method in [`treelib/tree.py`](https://github.com/caesar0301/treelib/blob/main/treelib/tree.py), which checks if the tree currently has a root and assigns the new node as root if the tree is empty and no parent is provided.