eggNOG-mapper v3: Orthology-Based Annotation Without the Best-Hit Guess

Why orthology beats a closest hit

eggNOG-mapper annotates novel sequences, whether proteins, coding sequences, genomes or metagenomes, using precomputed orthology data from the eggNOG database. The functional terms it transfers cover GO, KEGG orthologs, pathways and modules, EC numbers, PFAM domains, CAZy families, BiGG reactions and more. The reason to use orthology rather than a similarity search is stated precisely: transferring from fine-grained orthologs is more precise than best-hit transfer because it avoids annotation from close paralogs. A best-hit pipeline takes whatever happens to be most similar, and in a genome full of duplicated genes that is regularly the wrong family member, with a wrong label attached and no signal that anything went wrong. The orthology route constrains the answer to a gene whose relationship to a characterised gene is known rather than merely similar.

v3 targets eggNOG 7 and drops eggNOG 5

The version boundary matters more here than in most tools, and it is called out first. v3 targets the eggNOG 7 database, roughly 59 million proteins across the tree of life, and it is not compatible with eggNOG 5 data. If you have an existing pipeline built on the 2.x line, this is a migration rather than an upgrade, and the databases have to be re-downloaded rather than reused. The database itself changed shape as well as content, moving to integer-encoded orthology and phylogeny-aware speciation events. The second headline change is curated-only functional donors, meaning only manually curated terms are used as annotation donors. That is aimed at stopping the propagation of automated misannotations, and the claim is that it achieves better coverage than v2 despite being more conservative, which is the interesting claim to test on your own data.

Three ways to run it, and what each one costs you

The tool is offered in three shapes and the table is a good way to decide. The free web service at eggnog-mapper.cgmlab.org is for small or moderate jobs with zero setup. An Apptainer or Singularity image is for reproducible runs on HPC clusters, where everything is bundled in a single .sif file. Pip or source installation is for pipelines and development, where you get a Python package and the databases yourself. Prebuilt images and databases are hosted at data.cgmlab.org/eggnog-mapper. The web service is also available through the European Galaxy server, which matters for groups who cannot install anything locally. The choice is really about who owns the data and who owns the compute, and for a genome pipeline the answer is usually the third option, because the run has to fit inside an existing workflow.

Installing the package and the search tools it drives

The install is a pip command, and the alternative is a clone and a local install.

pip install eggnog-mapper

git clone https://github.com/eggnogdb/eggnog-mapper.git
cd eggnog-mapper && pip install .

Python 3.9 or newer is required, and the tool expects the search programs on your PATH. DIAMOND is the default seed search backend, MMseqs2 is an optional backend selected with `-m mmseqs`, Prodigal handles gene prediction for genome and metagenome input, and HMMER is only needed for the `--pfam_realign` option. A conda line installs all four at once. In the Apptainer image all of them are bundled, so nothing has to be installed there. That dependency on external binaries is the main operational difference from a pure library, and it is why the container route exists.

The 45 GB database and how it is versioned

The data download is the heaviest part of the setup and the versioning rules are specific. Data is versioned by MAJOR.MINOR, in directories named emapper-3.0, and pinned to the eggNOG database version. A minor bump, from 3.0 to 3.1, means the database changed and must be re-downloaded, while patch releases reuse the same data. The download command takes the data directory explicitly.

python download_eggnog_data.py -y --data_dir /path/to/data

The core download is about 45 GB, covering the annotation database, the DIAMOND database, the taxonomy data and prebuilt caches, and you add the optional MMseqs2 database with the `-M` flag and Pfam with `-P`. The rule that patch releases reuse data is the one to note, because it means a routine release does not cost you another 45 GB, but a minor bump does, and a pipeline that assumes a stable path has to handle that.

Running it, reading the output and checking the install

The quick start covers the input types you are likely to have.

# Proteins (default input type)
emapper.py -i proteins.fa -o my_run --data_dir /path/to/data --cpu 8

# CDS / genome / metagenome
emapper.py -i cds.fna       --itype CDS        -o my_run --data_dir DATA --cpu 8
emapper.py -i genome.fna    --itype genome     -o my_run --data_dir DATA --cpu 8
emapper.py -i contigs.fna   --itype metagenome -o my_run --data_dir DATA --cpu 8

The input type is explicit for anything that is not protein, and the run name is the prefix for the outputs. The main output is a 22-column TSV named with the run prefix and the .emapper.annotations suffix, with optional xlsx, orthologs and gff outputs alongside it. The columns were compacted in v3 and now include a positional annotation_confidence field carrying per-source confidence, with the column meanings documented in the output header. The most useful new command is the self-test, which downloads a small reference set and verifies that the install reproduces the expected annotations.

emapper.py --selftest

That is a cheap answer to a question that otherwise only shows up hours into a large run. Other additions include gzip and bzip2 input autodetection, Cython-accelerated inner loops, and a `--resume` option for interrupted runs, which matters on a cluster job that can be preempted. The taxonomic scope handling changed too, with a per-seed taxonomic ceiling under `--tax_scope auto` as the default, replacing the old predefined scope lists, so each seed narrows to its most informative level, though fixed clades such as Metazoa and 33208 are still accepted. A cascade annotation engine with a lazy closest-cascade on by default, plus seed sorting and de-duplication, is claimed to give large speedups on redundant proteome or UniProt scale inputs with byte-identical output.

What lives in the repository and what the packaging does

The repository holds the tool, its data tooling and its tests. There is the emapper.py entry point, an eggnogmapper/ package, download_eggnog_data.py and create_dbs.py for the database side, hmm_server.py and hmm_worker.py for the HMMER part, an apptainer/ directory with a build script that bundles DIAMOND, MMseqs2, HMMER and Prodigal, plus test_datasets/ and tests/. The packaging detail is worth understanding because it explains the performance claim. The build script wires in two Cython extensions inside the annotator, a codec and the ortholog-collector inner loop, and the key property is that if Cython is missing or the C compile fails, the install skips the extensions and the runtime shims fall back to pure-Python implementations that produce byte-identical results. The codec module picks the backend at import time, so a build without a compiler still works and still gives the same answer, just slower. The runtime dependencies are biopython, psutil and xlsxwriter.

Licence, version state and how to decide

The licence is AGPL-3.0, which is the more demanding of the two copyleft licences for a tool you might wrap in a pipeline, so it is worth reading before you deploy it internally and particularly before you expose it as a service. The release state is worth noting: the most recent tag is v3.0.0-beta6 from 2026-08-13, which means the 3.0 line is still in beta while the 2.x line was at 2.1.14 in May 2026 and 2.1.13 in June 2025, so the stable path and the new path are quite different. The last push was on 2026-08-13, and the repository holds a CHANGELOG.md and a USAGE.md that the readme points to as the complete manual, covering basic usage, databases, output format, Apptainer, advanced options and maximum-performance tips for HPC clusters. If you are evaluating this, the decision hinges on one thing: whether the curated-only donor policy gives you coverage you can live with on your own sequences.

Editorial conclusion

eggNOG-mapper fits a team annotating proteins or metagenomes at scale that wants orthology-based transfer with curated donors and a self-check command, and that can host the 45 GB database on local disk. It is the wrong choice if you need eggNOG 5 compatibility, which v3 explicitly drops, or if you cannot run the search tools the pipeline shells out to. Before you plan a large run, run emapper.py --selftest and check that your install reproduces the expected annotations.

Frequently asked questions

Official sources

1. eggnogdb/eggnog-mapper on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases