ETE 3 (Environment for Tree Exploration)

3.1.3 · maintenance · verified Thu Apr 16

ETE (Environment for Tree Exploration) 3 is a Python toolkit for the manipulation, analysis, and visualization of phylogenetic and other hierarchical trees. While version 4 is the actively developed major release, ETE 3.1.3 is the last stable version of the 3.x series, primarily receiving maintenance updates. It offers a comprehensive API for tree handling, node annotation, and customizable tree drawing into various image formats.

Common errors

```
ImportError: cannot import name TextFace
```
cause This usually indicates a problem with the PyQt or Qt installation, or a conflict between installed `ete3` and `ete3_external_apps` versions, or a missing graphical dependency like `xvfb`.

fix Ensure `PyQt5` is correctly installed (`pip install PyQt5` or `conda install pyqt`). If using Conda with `ete_toolchain`, try reinstalling `ete` and `pyqt` together. For headless environments, install `xvfb`.
```
ete3 build fails with 'decode_string()' no longer used
```
cause This error points to a Python version incompatibility, specifically when using Python 3.9+ with older parts of the `ete3` codebase that relied on deprecated `base64` functions.

fix Downgrade your Python environment to 3.6, which is the recommended version for full `ete3` and `ete_toolchain` compatibility. Use Conda to create a dedicated environment: `conda create -n ete3_env python=3.6`.
```
ete3 evol fails with 'ERROR: model M0 failed, problem with outfile:'
```
cause This often occurs when `ete3 evol` cannot find or properly execute the external programs (like `codeml`) it depends on, or there are issues with input files (e.g., malformed FASTA, tree without branch lengths).

fix Verify that `ete_toolchain` is correctly installed and its components are executable. Check your input FASTA and Newick files for correct formatting. Run `ete3 upgrade-external-tools` to ensure external tools are set up correctly.

Warnings

breaking ETE 4 (released as `ete4` on PyPI, but also updating the `ete` package) introduced significant breaking API changes from ETE 3. Code written for ETE 3 will not run directly with ETE 4 without modifications.
Fix: If migrating to ETE 4, consult the 'Migrating from ETE 3' documentation. If staying with ETE 3, ensure you install `ete==3.1.3` or `ete<4`.
deprecated Python 2 support was officially dropped in ETE 3.1.2. While ETE 3.1.0 and 3.1.1 had some Python 3 compatibility, 3.1.2 onward is Python 3-focused. Python 3.6 was specifically recommended for full compatibility with the `ete_toolchain` package. Using newer Python versions (e.g., 3.9+) might encounter issues with older `ete3` components.
Fix: Use Python 3.6 for optimal compatibility, especially with `ete_toolchain`. If using a newer Python 3 version, be prepared for potential dependency conflicts or runtime errors with certain `ete3` modules.
gotcha Graphical features (e.g., `Tree.show()`, `Tree.render()`) in ETE 3 rely on PyQt. Early `ete3` versions had compatibility issues with `PyQt5 >= 5.12`, leading to rendering problems. These were largely addressed in ETE 3.1.3. Conflicts with `PyQt4` and `PyQt5` installations, or missing `xvfb` for headless rendering, are common sources of errors.
Fix: Ensure `ete==3.1.3` is installed. For graphical features, install `PyQt5` (`pip install PyQt5`) or `PyQt4` (for older versions/environments where it's still available). If running in a headless environment, `xvfb` might be needed (`sudo apt-get install xvfb`). Check your display server configuration.
gotcha `ete3-build` and `ete3-evol` commands often require external bioinformatics tools (e.g., MAFFT, FastTree, Codeml) which are not bundled with the core `ete` Python package. These are best installed via the `ete_toolchain` Conda package. Manual compilation or incorrect paths can lead to command failures.
Fix: Use the Conda installation method with `conda install -c etetoolkit ete ete_toolchain`. If manual installation is necessary, run `ete3 upgrade-external-tools` and address any compilation errors for individual tools. Ensure external tool binaries are in your system's PATH.

Install

pip install ete==3.1.3 Install specific ETE 3.1.3 version
conda create -n ete3_env python=3.6 conda activate ete3_env conda install -c etetoolkit ete==3.1.3 ete_toolchain Recommended Conda install with toolchain

Imports

Tree
```
from ete3 import Tree
```
PhyloTree
```
from ete3 import PhyloTree
```
TreeStyle
wrong:
```
from ete3.treeview import TreeStyle
```
correct:
```
from ete3 import TreeStyle
```
All core drawing classes are usually imported directly from `ete3`.
NodeStyle
```
from ete3 import NodeStyle
```
AttrFace
```
from ete3 import AttrFace
```
TextFace
```
from ete3 import TextFace
```

Quickstart

This quickstart demonstrates how to create a simple phylogenetic tree from a Newick string, access and annotate its nodes, and prepare a custom visualization style. For graphical output (rendering to file or interactive display), `PyQt5` is required.

from ete3 import Tree, TreeStyle, NodeStyle, TextFace

# Create a tree from a Newick string
t = Tree("((A:1.0,B:1.0):0.5,C:1.5);")

# Print the tree topology to console
print("Tree topology:")
print(t.get_ascii(show_length=True))

# Access nodes and add features
for node in t.traverse():
    node.add_features(my_feature="value")
    if node.is_leaf():
        print(f"Leaf name: {node.name}, feature: {node.my_feature}")
    else:
        print(f"Internal node: {node.name if node.name else 'Unnamed'}, feature: {node.my_feature}")

# Create a custom tree style
ts = TreeStyle()
ts.show_branch_length = True
ts.show_branch_support = True
ts.show_leaf_name = True
ts.title.add_face(TextFace("My Phylogenetic Tree"), column=0)

# Render the tree to a file (requires PyQt5)
# t.render("my_tree.png", w=600, h=600, tree_style=ts)

# For interactive visualization (requires PyQt5 and an X server/display)
# t.show(tree_style=ts)

print("Quickstart complete. For visualization, uncomment t.render() or t.show() and ensure PyQt5 is installed.")

view raw JSON →