Installation

Funannotate2 can be installed with Docker (recommended), with pixi, or with conda/pip.

Using the Docker image

A pre-built image containing funannotate2, funannotate2-addons, helixerlite, all bioconda tooling, and the databases from funannotate2 install -d all is published on each tagged release to:

  • Docker Hub: nextgenusfs/funannotate2

  • GHCR: ghcr.io/nextgenusfs/funannotate2

Tags follow SemVer (e.g. :26.2.12, :26.2) with :latest always pointing at the most recent release.

# pull the latest image (~8 GB; databases are baked in)
docker pull nextgenusfs/funannotate2:latest

# sanity checks
docker run --rm nextgenusfs/funannotate2:latest funannotate2 --version
docker run --rm nextgenusfs/funannotate2:latest funannotate2 install -s

# run against a local data directory, persisting the BUSCO cache across runs
mkdir -p $PWD/data $PWD/busco_cache
docker run --rm -it \
    -v $PWD/data:/data \
    -v $PWD/busco_cache:/opt/busco_cache \
    -e BUSCO_DOWNLOAD_PATH=/opt/busco_cache \
    nextgenusfs/funannotate2:latest \
    funannotate2 predict -i /data/genome.fa -o /data/out --species "My species"

Notes:

  • The image is linux/amd64 only. On Apple Silicon it runs under Rosetta 2 emulation (Docker Desktop handles this automatically).

  • BUSCO lineages are not bundled — at ~90 GB uncompressed they exceed Docker Hub’s size ceiling. Mount a host directory (as shown above) so lineages download once and are reused.

  • GeneMark is not included due to licensing. If you need it, install it on the host and mount it into the container.

  • FUNANNOTATE2_DB is already set to /opt/funannotate2_db inside the image; no host setup required unless you want to override it.

Installing with pixi

If you prefer a native install on Linux without Docker, the repository ships a pixi workspace (pixi.toml / pixi.lock) that resolves the same environment used to build the Docker image.

# install pixi once (see https://pixi.sh/latest/#installation for alternatives)
curl -fsSL https://pixi.sh/install.sh | bash

# clone the repo and install the locked environment
git clone https://github.com/nextgenusfs/funannotate2.git
cd funannotate2
pixi install --locked

# activate the environment
pixi shell

# set the database location and install databases
export FUNANNOTATE2_DB=/path/to/funannotate2-db
funannotate2 install -d all

The pixi environment is currently defined for linux-64 only. macOS users should use the Docker image.

Requirements

Funannotate2 has the following dependencies:

  • Python 3.7 or later

  • Minimap2

  • Miniprot

  • SNAP

  • Augustus (==3.5.0)

  • GlimmerHMM

  • GeneMark-ES/ET [optional]

  • Diamond

  • tRNAscan-SE

  • table2asn

  • natsort

  • numpy

  • mappy

  • gfftk (>=24.10.29)

  • BUSCOlite (>=24.7.29)

  • gapmm2

  • pyhmmer (>=0.12.0)

  • pyfastx (>=2.0.0)

  • requests

  • gb-io (>=0.3.2)

  • json-repair

  • pytantan

Some tools like GeneMark-ES/ET must be installed manually due to licensing restrictions (see below).

Installing with conda

Funannotate2 can also be installed with conda/mamba:

mamba create -n funannotate2 gfftk gapmm2 minimap2 miniprot snap "augustus==3.5.0" glimmerhmm diamond trnascan-se table2asn gb-io buscolite
conda activate funannotate2
python -m pip install git+https://github.com/nextgenusfs/funannotate2.git

Installation on apple silicon (M series) is a little bit more involved due to some dependency issues and non-native builds of some software. I’ve not been able to find or build a version of augustus that will run, so instead I’ve been running augustus and genemark locally with Docker. I’ve setup two repos with instructions on how to get this working (Need Docker Desktop installed) and then will need to put the bash wrapper files in your PATH to mimic the CLI interface.

https://github.com/nextgenusfs/dockerized-augustus

https://github.com/nextgenusfs/dockerized-genemark

Once that is working, you can then install most of the remaining dependencies with conda, although we need to leave out both buscolite and funannotate2 because they have augustus as a dependency, instead we will install those python packages with pip.

# first install most of the dependencies
mamba create -n funannotate2 --platform osx-64 "python>=3.7,<3.13" gfftk gapmm2 minimap2 miniprot snap glimmerhmm diamond trnascan-se gb-io pyhmmer pyfastx requests json-repair "mkl<2022" pytantan

# we can then add the required FUNANNOTATE2_DB env variable to the conda environment, note need to reactivate to use it
conda activate funannotate2
conda env config vars set FUNANNOTATE2_DB=/path/to/funannotate2-db
conda env config vars set AUGUSTUS_CONFIG_PATH=/path/to/augustus-3.5.0/config
conda deactivate

# now reactivate environment, and install the remaining python dependencies with pip
conda activate funannotate2
python -m pip install buscolite git+https://github.com/nextgenusfs/funannotate2.git

# now we can install the databases
funannotate2 install -d all

Installing with pip

To install the latest release version using pip:

pip install funannotate2

To install the development version directly from GitHub:

pip install git+https://github.com/nextgenusfs/funannotate2.git

Verifying Installation

To verify that Funannotate2 is installed correctly:

funannotate2 --version

This should display the version of Funannotate2.

Installing Databases

Funannotate2 requires several databases to be installed. Note: funannotate2 scripts expect the $FUNANNOTATE2_DB environment variable to be set. These can be installed using the following command:

funannotate2 install -d all

Installing GeneMark

GeneMark-ES/ET must be installed manually due to licensing restrictions:

  1. Register and download GeneMark-ES/ET from the GeneMark website

  2. Follow the installation instructions provided with the download

  3. Make sure the GeneMark executables are in your PATH

  4. You may also need to install GeneMark specific perl libraries, specifically perl-hash-merge and perl-mce have been mentioned by users adding to the existing conda environment.