GTDB-Tk: placing metagenome genomes into the GTDB taxonomy

Why metagenome assemblies need an objective label

GTDB-Tk is a software toolkit for assigning objective taxonomic classifications to bacterial and archaeal genomes based on the Genome Database Taxonomy, the GTDB. The word objective in that sentence is doing the work, and it reflects the way the field has moved: taxonomy for genomes recovered from environmental samples is now expected to come from a fixed reference set and a defined pipeline rather than from a curator's judgement.

The tool is designed around recent advances that allow hundreds or thousands of metagenome-assembled genomes, MAGs, to be obtained directly from environmental samples, and it also applies to isolate and single-cell genomes. That second point matters. A MAG is not a cultured isolate with a clean isolation record; it is a bin reconstructed from a mixed community sample, so it needs a defensible way to say what it is closest to.

GTDB is the reference. It is a phylogenetically consistent, rank normalised, complete genome based taxonomy, and the GTDB-Tk workflow compares user genomes against the GTDB representative genomes so that the label a user gets is the label the database would give.

Two audiences follow from that. The first is the metagenomics researcher who has hundreds of bins and needs them classified consistently with the wider field, so results can be compared across studies. The second is the person building a reference database, who needs the same classification rule applied to their own isolates so the labels line up with GTDB naming. The toolkit is open source and released under the GNU General Public License version 3.

The ANI screen and the memory cost that comes with it

The mechanism has two stages, and understanding the order explains the resource requirements.

First there is the ANI screen, a fast comparison against the reference set. Using it can reduce computation by more than 50 percent, but the README is careful about when that holds. A set of input genomes consisting primarily of new species will not benefit as much as a set of genomes that are largely assigned to existing GTDB species clusters. In the latter case the ANI screen reduces the number of genomes that need to be classified by pplacer, reducing computation time substantially, between 25 and 60 percent in the authors' testing. In other words, the screen is a filter that helps most when most of your genomes are already known.

Second, the surviving genomes go through phylogenetic placement, and this is where the memory comes from. Since version 2.7.0 the pipeline uses a skani pre-sketched database of the GTDB representative genomes, a single sketch rather than per-genus comparisons, and the README warns in capitals that the divide and conquer approach now requires more than 128 GB of RAM, specifically at least 140 GB of RAM for R232.

The storage side improved while the memory side grew. The pre-sketched database cuts the storage footprint from 198 GB in Release 232 down to 98 GB, and the representative genomes are now downloadable from the Download page on the GTDB website rather than assembled by the user.

One flag moved with that change. `--skip_ani_screen` is deprecated in v2.7.0 and replaced by `--place_species`. Because the database is now one sketch, user genomes are compared against all GTDB reference genomes once at the start of the pipeline, and with `--place_species` selected the genomes are still explicitly placed in the reference tree. The `--skani_sketch_dir` flag is deprecated too, since the database is already sketched natively.

Installing it and running the first classification

The README sends you to the hardware requirements page first, then offers three installation routes: Bioconda, Docker and pip. Each has its own page in the documentation, and the exact commands live there rather than in the README, so take the installation string from the route you choose.

The Docker image is the easiest to reason about, and the Dockerfile in the repository carries the working invocation in its header comments. Two volumes are mounted: one for your input and output directory, one for the reference data, and the tool is called with the classify_wf workflow:

# docker run -v /host/gtdbtk_io:/data -v /host/release_data:/refdata ecogenomic/gtdbtk classify_wf --genome_dir /data/genomes --out_dir /data/output

What you should see is a classify_wf run over the genomes in /data/genomes writing into /data/output, using the reference package mounted at /refdata. The image is published as ecogenomic/gtdbtk on Docker Hub and is tagged by date, so you can pin the version you validated.

The image itself is built on python:3.11-slim-bookworm and installs the external tools the workflow depends on, including HMMER, Prodigal for gene prediction and FastTree, plus pplacer for phylogenetic placement. The Python side of the package is installed through setup.py, and its dependency list is short and pinned:

    install_requires=["dendropy ~= 4.1", 'numpy ~= 1.9', 'tqdm ~= 4.35', 'pydantic ~= 1.9'],

Those are the Python dependencies only. The heavy lifting in the workflow comes from the binaries and the reference database, which is why the container image exists at all.

Two workflows, and the v2.8.0 rule change that bites

GTDB-Tk has two entry points and they are not interchangeable. `classify` reports one set of metadata. `classify_wf` is the workflow that runs the full pipeline, and until v2.8.0 the two could disagree.

The change is specific and worth understanding. In v2.8.0, `classify` and `classify_wf` now report the same metadata. `other_related_references` lists only references with AF at or above `--min_af`, closest first, and genomes not assigned by the ANI screen now report their closest references and warnings in `classify_wf` as well.

The behavioural difference involves fuzzy species in condensed genera, and the README gives a worked example. A genome has 97 percent ANI to representative A, a fuzzy species with a radius of 98 percent, and 96 percent ANI to representative B whose radius is 95 percent, both with AF at or above 0.5. A is the closest reference, but the genome falls outside A's ANI radius. In v2.7.x, `classify_wf` assigned the genome to B's species. In v2.8.0 it leaves the species unassigned, shows as `s__`, lists A and B in `other_related_references`, and adds a warning that the genome falls outside the closest representative's ANI radius. The reason is that species in condensed genera are circumscribed more narrowly, with an ANI radius above the default 95 percent, and v2.8.0 applies the rule `classify` has always used.

The README states the scope of that change: classifications are otherwise unchanged, and in the authors' tests it affected fuzzy species in condensed genera in 4 of 10,000 GlobDB genomes. That is a small number, but it is the difference between a species label and no label, so any pipeline that compares results across versions needs to account for it.

There is a related operational detail. Output directories whose ANI screen was produced by an earlier version are re-screened when resumed, so a long run that is interrupted and restarted does not silently mix screens from different versions.

What the tool will not do for you

The first limitation is the one the README shouts about: memory. At least 140 GB of RAM for R232, with more than 128 GB required by the new approach. On a workstation or a typical analysis node this is not a detail, it decides whether the pipeline can run at all, and the same requirement applies whether you use classify_wf or the Docker image, since the container does not change the memory profile of the algorithm.

The second is the reference data. Roughly 98 GB has to be downloaded and stored, and the reference package is versioned against the tool. v2.8.0 uses the same R232 reference package as v2.7.x, which is convenient, but it means the tool version and the database version are a pair you have to track. A database from a different release is not interchangeable, and the repository does not provide a way to mix them.

The third is scope. GTDB-Tk classifies genomes against GTDB. It does not give you functional annotation, it does not resolve a genome into contigs, and it does not do anything with viruses or eukaryotes, since the reference set covers bacteria and archaea. If your pipeline needs those, they are separate tools and separate reference decisions.

The fourth is the naming convention itself. GTDB labels are not NCBI labels, and the repository ships a console script named gtdb_to_ncbi_majority_vote for converting GTDB assignments to the NCBI-style majority vote naming that downstream databases tend to expect. That script is a conversion tool, not a statement that the two taxonomies agree, and results that get converted this way lose the rank-level precision GTDB was built to provide.

Phylogenetic placement versus marker based assignment

There is a different way to answer the same question, and the difference is worth being explicit about.

A marker based approach assigns a taxon by comparing a small region, such as the 16S ribosomal RNA gene or a handful of protein markers, against a reference set of aligned sequences. It is cheap, it runs on a laptop, and it returns a label with a known precision limit, since a marker gene does not always discriminate between closely related species and the label degrades to genus level more often than a genome based method.

A phylogenetic placement approach, which is what GTDB-Tk does, compares the whole genome against reference genomes and places it in a tree. The label follows from tree position under a defined rule, which is why the README can describe the classifications as objective. The cost is the reference data, the external tools, and the memory to hold the comparison in the working set.

The practical consequence is that the two approaches are not interchangeable in a pipeline. If you need labels that match what GTDB will publish, only GTDB-Tk gives you that. If you need a fast triage to sort thousands of bins into rough groups before spending compute on the ones that matter, a marker based screen is the right first pass and GTDB-Tk the second, and the ANI screen inside GTDB-Tk is itself a version of that idea applied at the species level.

The choice also depends on reproducibility expectations. A GTDB label is tied to a database release and a tool version, and v2.8.0 shows how those combinations can shift results at the species level. If your dataset has to be re-analysed in two years, record the tool version, the reference release and the flags you used, because the defaults themselves have moved.

Licence, releases and where to ask questions

GTDB-Tk is open source under the GNU General Public License version 3. That is a copyleft licence, so if you distribute a derived version of the software you owe the recipients the corresponding source, while using it inside your own analysis pipeline is unencumbered. The licence covers the code; the GTDB reference data and the naming it produces come with their own terms, which are a separate question for a commercial pipeline.

The maintenance picture is healthy and unusually explicit for a scientific tool. Version 2.8.0 was released on 2026-10-13, after 2.7.2 on 2026-05-08 and 2.7.1 on 2026-04-17. The repository is not archived and the last push was on 2026-10-20. The README points at a changelog page for the full list of changes, and release notifications go out through the GTDB Bluesky account and the GTDB Announcements forum, which is a sensible arrangement for a tool whose output vocabulary can change under you.

Support channels are split by topic, and the split matters for triage. Questions and issues related to GTDB-Tk go in the GitHub Issues section of the repository, while questions about GTDB itself go to the GTDB Forum or to the GTDB team. The package also declares itself as Production/Stable in its setup.py classifiers and is published on PyPI and Bioconda, so it can be installed the standard way in an analysis environment.

For a paper, the README asks you to cite the two GTDB-Tk papers, the 2022 Bioinformatics paper on memory friendly classification and the 2019 paper describing the toolkit, and the GTDB database paper where appropriate.

Editorial conclusion

Adopt GTDB-Tk when you have metagenome-assembled genomes or isolate genomes that must be labelled against the GTDB taxonomy, you can supply a machine with at least 140 GB of RAM for the R232 reference package, and you need the classification rules to be objective rather than hand curated. Do not adopt it for a quick annotation pass on a small set of genomes, since the memory and database costs are fixed, and do not carry over results from a run that used the deprecated --skip_ani_screen flag without re-screening, since v2.8.0 re-screens output directories produced by an earlier version when they are resumed. Before you start, read the hardware requirements page, download the matching R232 reference data, and record which GTDB-Tk version produced each result set.

Frequently asked questions

Official sources

1. Ecogenomics/GTDBTk on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases