# How to Paste a Subtree to a Parent Node in treelib: Complete Guide with Examples > Learn to paste a subtree to a parent node in treelib using Tree paste and subtree methods. This guide provides clear examples for efficient tree manipulation with treelib. - Repository: [Xiaming Chen/treelib](https://github.com/caesar0301/treelib) - Tags: how-to-guide - Published: 2026-02-26 --- **To paste a subtree to a parent node in treelib, use `Tree.paste(nid, new_tree, deep=False)` after extracting the branch with `Tree.subtree(nid)`, where `deep=True` creates independent copies of all nodes.** The `treelib` library manages tree structures through the `Tree` class in [`treelib/tree.py`](https://github.com/caesar0301/treelib/blob/main/treelib/tree.py), which maintains a dictionary of `Node` instances and their hierarchical relationships. Combining the `subtree()` and `paste()` methods enables you to move or duplicate entire branches between different trees or within the same tree. This guide explains the internal mechanics of these operations and provides production-ready code examples. ## How `paste()` Attaches a Subtree to a Parent Node The `paste()` method, implemented in [`treelib/tree.py`](https://github.com/caesar0301/treelib/blob/main/treelib/tree.py) (lines 1534–1564), inserts an entire tree structure under an existing node by manipulating internal pointers and node registries. The implementation follows a strict four-phase process to ensure data integrity. ### Input Validation and Identifier Collision Checks First, the method validates that the source `new_tree` contains a root node and that the target `nid` exists in the destination tree. It then iterates through `new_tree._nodes` to verify that no identifier collisions exist with the destination tree's existing nodes. If conflicts are detected, the method raises a `NodeIDAbsentError` defined in [`treelib/exceptions.py`](https://github.com/caesar0301/treelib/blob/main/treelib/exceptions.py). ### Node Copying and Pointer Rewiring The method processes each node in the source subtree. When `deep=True`, it creates a deep-copied `Node` object using Python's `deepcopy` module. Each node is registered in the destination tree's `_nodes` dictionary. The `node.clone_pointers()` method (from [`treelib/node.py`](https://github.com/caesar0301/treelib/blob/main/treelib/node.py)) rewires the node's internal parent and child references from the source tree's identifier system to the destination tree's identifier system. ### Root Re-linking to the Parent Node Finally, the method attaches the subtree root to the target parent using two private helper methods: `self.__update_bpointer(new_tree.root, nid)` sets the pasted root's backward pointer to the new parent, and `self.__update_fpointer(nid, new_tree.root, self.node_class.ADD)` updates the forward pointer of the parent node to include the new child in its successor list. ## Extracting a Subtree with `subtree()` Before pasting, isolate the target branch using `Tree.subtree(nid)`, implemented in [`treelib/tree.py`](https://github.com/caesar0301/treelib/blob/main/treelib/tree.py) (lines 1883–1895). This method creates a shallow copy of the requested branch where the node objects are shared between the original and extracted tree, but the root pointer changes to the specified `nid`. The shallow copy approach minimizes memory overhead, but modifications to shared nodes will affect both trees unless you use the `deep=True` parameter during the paste operation. ## Practical Example: Moving a Branch Between Trees The following example demonstrates building a source tree, extracting a subtree rooted at node "A", and pasting it under a new parent in a destination tree using both shallow and deep copy modes. ```python from treelib import Tree # Build source tree src = Tree() src.create_node("root", "root") src.create_node("A", "A", parent="root") src.create_node("B", "B", parent="root") src.create_node("C", "C", parent="A") src.create_node("D", "D", parent="A") src.show() # └── root # ├── A # │ ├── C # │ └── D # └── B # Extract subtree rooted at "A" sub = src.subtree("A") # Shallow copy of A-branch # Build destination tree dst = Tree() dst.create_node("new_root", "new_root") dst.create_node("X", "X", parent="new_root") dst.show() # └── new_root # └── X # Paste subtree under node "X" (shallow paste) dst.paste(nid="X", new_tree=sub) dst.show() # └── new_root # └── X # └── A # ├── C # └── D # For independent copies, use deep=True dst2 = Tree() dst2.create_node("new_root2", "new_root2") dst2.create_node("Y", "Y", parent="new_root2") dst2.paste(nid="Y", new_tree=sub, deep=True) ``` ## Shallow vs. Deep Paste Operations Understanding the copy semantics is critical when you paste a subtree to a parent node in treelib: - **Shallow paste** (`deep=False`): Reuses the original `Node` objects from the source subtree. This is memory-efficient but means modifications to node attributes (such as tags or data) will affect both the source and destination trees because they reference the same object instances. - **Deep paste** (`deep=True`): Creates independent copies of all nodes using Python's `deepcopy`. Mutations in the pasted branch do not affect the original tree, but this consumes additional memory and processing time during the paste operation. ## Summary - Use `Tree.subtree(nid)` to isolate a branch from an existing tree before pasting; this creates a shallow copy of the branch structure. - Call `Tree.paste(nid, new_tree, deep=False)` to attach the subtree under the specified parent node in the destination tree. - The implementation in [`treelib/tree.py`](https://github.com/caesar0301/treelib/blob/main/treelib/tree.py) validates inputs, checks for identifier collisions, and rewires internal pointers using `clone_pointers()`. - Choose `deep=True` when you need independent node copies to prevent side effects on the source tree; use the default shallow paste for memory-efficient operations when shared references are safe. ## Frequently Asked Questions ### What happens if node identifiers collide when pasting a subtree? The `paste()` method raises a `NodeIDAbsentError` (defined in [`treelib/exceptions.py`](https://github.com/caesar0301/treelib/blob/main/treelib/exceptions.py)) if any identifier in the source subtree already exists in the destination tree's `_nodes` dictionary. You must ensure all node IDs are unique across both trees before pasting, or remap the identifiers in the source subtree first. ### Can I paste a subtree to the root node of another tree? Yes. Pass the root node's identifier as the `nid` parameter to `paste()`. The method uses `__update_bpointer()` and `__update_fpointer()` to attach the subtree root as a child of the specified node, which can be any existing node including the tree root. ### Does `subtree()` modify the original tree? No. The `subtree()` method in [`treelib/tree.py`](https://github.com/caesar0301/treelib/blob/main/treelib/tree.py) (lines 1883–1895) creates a shallow copy of the branch without altering the original tree's structure or nodes. However, because it performs a shallow copy, modifications to the extracted nodes will affect the original tree unless you use `deep=True` during the paste operation or manually deep-copy the subtree before pasting. ### How do I move a node and all its descendants to a new parent without keeping them in the original location? First extract the branch with `subtree(nid)`, then remove it from the source tree using `remove_node(nid)`, and finally paste it to the new parent with `paste()`. Note that `subtree()` alone does not remove the branch from the source; it only creates a copy suitable for attachment elsewhere.