gtdb-genomes

gtdb-genomes downloads NCBI genomes from GTDB taxon selections.

It uses included Genome Taxonomy Database (GTDB) taxonomy tables and NCBI datasets CLI.

The detailed guide covers the Runtime Contract, Output Layout, Retry Policy, and GTDB Taxonomy Data.

Installation

The published package is available from Bioconda:

mamba create -n gtdb-genomes -c conda-forge -c bioconda gtdb-genomes
mamba activate gtdb-genomes
gtdb-genomes --help

The Bioconda package currently constrains the packaged runtime to:

• polars >=1.31.0,<2.0.0
• tqdm >=4.60.0,<5.0.0
• ncbi-datasets-cli >=18.4.0,<19.0.0
• unzip >=6.0,<7.0

For packaging and redistribution details, see GTDB Taxonomy Data.

Quick Start

gtdb-genomes -t g__Escherichia -o results

Command options

Short version:

• -t, --gtdb-taxon: exact GTDB taxon name(s)
• -o, --outdir: defaults to the current working directory; aborts if leftover GTDB-genomes run artefacts are detected there
• -r, --gtdb-release: defaults to latest
• --prefer-genbank and --version-latest: live NCBI metadata modes
• --include: locally supported values are genome, gff3, and protein
• -j, --threads and -d, --dry-run are also available, alongside --keep-tmp, --ncbi-api-key, and --debug

For full option behaviour, see Options, API Key Handling, Retry Policy, Runtime Contract, and Summary Files.

Note

The software aborts when the output root already contains leftover GTDB-genomes artefacts from a previous run. Existing unrelated files are allowed, but reserved run artefacts such as taxa/, run_summary.log, or .gtdb_genomes_work/ block a new run until they are removed or a different output directory is chosen.

Important

--ncbi-api-key expects an NCBI API key. The tool passes it only to the datasets command and does not use it for GTDB release resolution, local taxonomy loading, or any other use.

Examples

Small download. Quote species names that contain spaces:

gtdb-genomes \
  --gtdb-taxon "s__Methanobrevibacter smithii" \
  --outdir results

Prefer paired GenBank accessions from current NCBI metadata, keep the exact selected version, and ask for extra annotation:

export NCBI_API_KEY="your-ncbi-api-key"
gtdb-genomes \
  --gtdb-taxon "p__Pseudomonadota" "c__Alphaproteobacteria" \
  --prefer-genbank \
  --include genome,gff3 \
  --outdir results

Ask for the latest available revision in the selected GenBank family from current NCBI metadata:

gtdb-genomes \
  --gtdb-release latest \
  --gtdb-taxon "s__Methanobrevibacter smithii" \
  --prefer-genbank \
  --version-latest \
  --outdir results/methanobrevibacter-latest

Dry-run with automatic planning:

gtdb-genomes \
  --gtdb-release 95 \
  --gtdb-taxon "s__Thermoflexus hugenholtzii" \
  --dry-run \
  --outdir /tmp/gtdb_dry_run

Caution

Metadata-confirmed suppressed genomes may no longer be downloadable from NCBI, especially in older GTDB releases. A run may therefore finish with suppressed-genome failures even when taxon selection is otherwise valid.

Note

Some legacy GTDB releases include genome accessions starting with UBA. These legacy accessions are not supported by NCBI and are not supported by gtdb-genomes. When selected, the tool warns and skips them. Check BioProject PRJNA417962, since most UBA genomes are assigned through that bioproject.

Output Layout

OUTPUT/
|-- accession_map.tsv
|-- download_failures.tsv
|-- duplicated_genomes.tsv
|-- run_summary.log
|-- taxon_summary.tsv
|-- debug.log                  # only when --debug is used
`-- taxa/
    |-- g__Escherichia/
    |   |-- taxon_accessions.tsv
    |   `-- GCA_000005845.2/
    `-- s__Escherichia_coli/
        |-- taxon_accessions.tsv
        `-- GCA_000005845.2/

Each run writes top-level manifests and one directory per requested taxon under OUTPUT/taxa/. For detailed layout rules and summary-file definitions, see Output Layout and Summary Files.

Contribution

Contributor setup and source-checkout notes are in CONTRIBUTING.md.

For runtime and packaging boundaries, see Runtime Contract and GTDB Taxonomy Data. For Bioconda recipe notes, see packaging/bioconda/README.md.

Licence

The project code and packaging glue are released under the MIT licence. Published release archives also include GTDB taxonomy data under CC BY-SA 4.0. See NOTICE and licenses/CC-BY-SA-4.0.txt for attribution and licence details.

Citation

You can copy and paste this citation:

Shima, A. (2026). gtdb-genomes (Version 0.2.2) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.19198946

Machine-readable citation metadata is also available in CITATION.cff.

Additional Documents

• Usage details
• Contributing
• Real-data validation guide
• Bioconda recipe
• Bioconda packaging notes