ETE Toolkit 4

Scope

Use ETE 4 to work with an existing tree:

• Read Newick/Nexus, then inspect, annotate, transform, root, prune, and write Newick trees
• Compare topologies and calculate phylogenetic distances
• Find repeated subtree topologies with TreePattern
• Analyze gene trees with PhyloTree
• Query local NCBI or GTDB taxonomy databases
• Explore large trees interactively with SmartView
• Render PNG with SmartView or PNG/PDF/SVG with the optional Qt treeview

ETE does not replace sequence alignment or phylogenetic inference software. For raw sequences, first use MAFFT or another aligner and IQ-TREE 2, FastTree, or another inference tool; then load the resulting tree into ETE.

Current Target

This skill targets ETE 4.4.0, released September 3, 2025 and verified as the current PyPI release on September 30, 2026. Core, phylogeny, local synthetic taxonomy and helper checks target this released package, not unreleased upstream changes. See references/review.md for executed coverage and limitations.

Use https://etetoolkit.github.io/ete/ for ETE 4 documentation. The etetoolkit.org/docs/latest pages are legacy ETE 3 documentation despite the URL name.

Do not silently translate these examples back to ETE 3:

• Package and import: ete4, not ete3
• File input: pass an open file object; use strings for Newick text and do not rely on path-string heuristics retained in ETE 4.4.0
• Newick selection: parser=, not format=
• Node metadata: props, add_prop(), and add_props()
• Iteration: leaves(), descendants(), and related methods return iterators
• Predicates: node.is_leaf and node.is_root are properties, not methods
• Node lookup: tree["name"], not tree & "name"

For porting older code, load references/migration-ete3-to-ete4.md.

Installation

Install the pinned base package:

uv pip install "ete4==4.4.0"

Add only the visualization extra required by the workflow:

# SmartView static PNG screenshots
uv pip install "ete4[render-sm]==4.4.0"

# Legacy Qt renderer for PNG, PDF, and SVG
uv pip install "ete4[treeview]==4.4.0"

Confirm the active environment:

uv run --no-project --isolated --with "ete4==4.4.0" python -c "import ete4; print(ete4.__version__)"

No credentials are required. NCBI and GTDB workflows download public taxonomy data and can consume substantial disk space; see references/taxonomy.md before the first update.

Quick Start

from pathlib import Path

from ete4 import Tree

# Use an open file object for files; reserve strings for Newick text.
with Path("tree.nw").open(encoding="utf-8") as handle:
    tree = Tree(handle, parser=1)  # parser 1: internal node names

print(tree.to_str(props=["name", "dist"], compact=True))
print("Leaves:", list(tree.leaf_names()))

# Search and annotate.
focal = tree["species1"]
focal.add_props(host="human", status="focal")

# Keep selected tips while preserving pairwise branch-length distances.
tree.prune(
    ["species1", "species2", "species3"],
    preserve_branch_length=True,
)

# Root and serialize explicitly.
tree.set_midpoint_outgroup()
tree.write(
    outfile="processed.nw",
    parser=1,
    props=["host", "status"],
)

Choose the parser deliberately. A parser mismatch is the most common cause of NewickError, lost internal labels, or support values being read as names. See references/api_reference.md.

Core Workflows

Inspect and transform a tree

from ete4 import Tree

tree = Tree("((A:1,B:1)CladeAB:0.4,C:2)Root;", parser=1)

for node in tree.traverse("preorder"):
    label = node.name if node.name is not None else node.id
    print(label, node.level, node.is_leaf, node.dist)

tree["A"].add_prop("group", "case")
tree["B"].add_prop("group", "control")

mrca = tree.common_ancestor("A", "B")
print(mrca.name)

tree.write(
    outfile="annotated.nhx",
    parser=1,
    props=["group"],
    format_root_node=True,
)

Node names need not be unique. tree["A"] returns the first match; use list(tree.search_nodes(name="A")) and validate the count when duplicates are possible.

Compare two topologies

from ete4 import Tree

tree_a = Tree("((A,B),(C,D));")
tree_b = Tree("((A,C),(B,D));")

(
    rf,
    max_rf,
    common_leaves,
    edges_a,
    edges_b,
    discarded_a,
    discarded_b,

…