{"id":8139,"library":"ete","title":"ETE 3 (Environment for Tree Exploration)","description":"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.","status":"maintenance","version":"3.1.3","language":"en","source_language":"en","source_url":"https://github.com/etetoolkit/ete","tags":["phylogenetics","tree","bioinformatics","visualization","biology","genomics"],"install":[{"cmd":"pip install ete==3.1.3","lang":"bash","label":"Install specific ETE 3.1.3 version"},{"cmd":"conda create -n ete3_env python=3.6\nconda activate ete3_env\nconda install -c etetoolkit ete==3.1.3 ete_toolchain","lang":"bash","label":"Recommended Conda install with toolchain"}],"dependencies":[{"reason":"Required for array and cluster tree support.","package":"numpy","optional":true,"affected_versions":">=3.1.0"},{"reason":"Optional, required for PhyloXML/NexML format parsing.","package":"lxml","optional":true,"affected_versions":">=3.1.0"},{"reason":"Optional, required for graphical tree visualization and image rendering (e.g., `tree.show()`, `tree.render()`). PyQt4 also compatible with older 3.x versions.","package":"PyQt5","optional":true,"affected_versions":">=3.1.0"},{"reason":"Python 2/3 compatibility layer (though Python 2 support dropped in 3.1.2).","package":"six","optional":false,"affected_versions":">=3.1.0"},{"reason":"Meta-package providing external tools for phylogenetic analysis (e.g., alignment, tree inference) used by `ete3-build` and `ete3-evol`. Primarily available via Conda.","package":"ete_toolchain","optional":true,"affected_versions":">=3.1.0"}],"imports":[{"symbol":"Tree","correct":"from ete3 import Tree"},{"symbol":"PhyloTree","correct":"from ete3 import PhyloTree"},{"note":"All core drawing classes are usually imported directly from `ete3`.","wrong":"from ete3.treeview import TreeStyle","symbol":"TreeStyle","correct":"from ete3 import TreeStyle"},{"symbol":"NodeStyle","correct":"from ete3 import NodeStyle"},{"symbol":"AttrFace","correct":"from ete3 import AttrFace"},{"symbol":"TextFace","correct":"from ete3 import TextFace"}],"quickstart":{"code":"from ete3 import Tree, TreeStyle, NodeStyle, TextFace\n\n# Create a tree from a Newick string\nt = Tree(\"((A:1.0,B:1.0):0.5,C:1.5);\")\n\n# Print the tree topology to console\nprint(\"Tree topology:\")\nprint(t.get_ascii(show_length=True))\n\n# Access nodes and add features\nfor node in t.traverse():\n    node.add_features(my_feature=\"value\")\n    if node.is_leaf():\n        print(f\"Leaf name: {node.name}, feature: {node.my_feature}\")\n    else:\n        print(f\"Internal node: {node.name if node.name else 'Unnamed'}, feature: {node.my_feature}\")\n\n# Create a custom tree style\nts = TreeStyle()\nts.show_branch_length = True\nts.show_branch_support = True\nts.show_leaf_name = True\nts.title.add_face(TextFace(\"My Phylogenetic Tree\"), column=0)\n\n# Render the tree to a file (requires PyQt5)\n# t.render(\"my_tree.png\", w=600, h=600, tree_style=ts)\n\n# For interactive visualization (requires PyQt5 and an X server/display)\n# t.show(tree_style=ts)\n\nprint(\"Quickstart complete. For visualization, uncomment t.render() or t.show() and ensure PyQt5 is installed.\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"ete>=4.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<3.1.2 (for Python 2.x), >3.6 (for `ete_toolchain` issues)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<3.1.3 (for PyQt5>=5.12), all (for PyQt setup issues)"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All `ete3` versions using `ete3-build` or `ete3-evol`."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","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`.","error":"ImportError: cannot import name TextFace"},{"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`.","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.","error":"ete3 build fails with 'decode_string()' no longer used"},{"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.","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).","error":"ete3 evol fails with 'ERROR: model M0 failed, problem with outfile:'"}]}