Trying Helixer

Helixer is a eukaryotic gene prediction tool published in 2025. I became interested in this area during my PhD, when I made extensive use of GeneMark-ES and Augustus.

Both Augustus and GeneMark-ES work well, but they are a bit dated. In addition, GeneMark-ES requires a custom license and a key. In contrast, Helixer is licensed under GPL-3.0 and is available on GitHub.

Today I tried running Helixer.

Installation

The authors provide both a Docker image and a manual installation path. Docker would be the easiest route, but since Helixer can use CUDA and I have an AMD GPU I will try the manual route first.

Since it appears to be a Python project, I chose uv to manage the virtual environment. I add custom ROCm install instructions to the pip command below:

uv venv -p 3.11
source .venv/bin/activate

# Install tensorflow for ROCm
uv pip install tensorflow-rocm -f https://repo.radeon.com/rocm/manylinux/rocm-rel-7.1.1/
# Now normally install the Helixer package
uv pip install git+https://github.com/usadellab/Helixer

This failed because Helixer has specific requirements that the commands above couldn’t meet, due to ROCm package versions.

Example screenshot:

I’m sure those are the versions used to build their local environment, but the version pinning seems stricter than necessary.

Since my ROCm setup appears to be the issue, I’ll try installing Helixer without GPU support first:

uv venv -p 3.11
source .venv/bin/activate

# Now normally install the Helixer package
uv pip install git+https://github.com/usadellab/Helixer

Note: Only Python 3.11 appears to work; I tried 3.10, 3.11, and 3.12, but only 3.11 could resolve the dependencies.

Getting a Genome

Next we need a genome. I use a CSV from NCBI to obtain the genome for the skin fungus Malassezia restricta. It’s likely this genome was part of the Helixer training dataset.

uv pip install polars jupyter

import polars as pl
url = "https://ftp.ncbi.nlm.nih.gov/genomes/ASSEMBLY_REPORTS/assembly_summary_refseq.txt"
url = "assembly_summary_refseq.txt"

# Note: long infer length often helps Polars to define the Schema better
# quote_char=None is needed because some fields contain unescaped quotes
df = pl.read_csv(url, separator="\t", skip_rows=1, infer_schema_length=100000, quote_char=None) 
df.head()

This CSV contains information about RefSeq genomes deposited in the NCBI GenBank.

df_m_restricta = df.filter(pl.col("organism_name") == pl.lit("Malassezia restricta"),
          pl.col("refseq_category") == pl.lit("reference genome"))
df_m_restricta.select(["#assembly_accession", "organism_name", "refseq_category", "ftp_path"])

import requests
from pathlib import Path

folder = Path("data")
folder.mkdir(exist_ok=True)

for row in df_m_restricta.iter_rows(named=True):
    ftp_path = row["ftp_path"]
    filename = ftp_path.split("/")[-1] + "_genomic.fna.gz"
    url = f"{ftp_path}/{filename}"
    print(f"Downloading {url} to {folder/filename}")
    response = requests.get(url)
    with open(folder/filename, "wb") as f:
        f.write(response.content)

Downloading https://ftp.ncbi.nlm.nih.gov/genomes/all/GCF/003/290/485/GCF_003290485.1_ASM329048v1/GCF_003290485.1_ASM329048v1_genomic.fna.gz to data/GCF_003290485.1_ASM329048v1_genomic.fna.gz

Running Helixer

Now that I have a genome I should be able to run the gene inference. The tutorial says to run:

Helixer.py \
  --lineage fungi \
  --fasta-path data/GCF_003290485.1_ASM329048v1_genomic.fna.gz  \
  --species Malassezia_restricta \
  --gff-output-path data/Malassezia_restricta_helixer.gff3

But this initially produced an error:

FileNotFoundError: [Errno 2] No such file or directory: '/home/paul/.local/share/Helixer/models/fungi'

It seems I needed to download the models first; I had skipped that step.

So I downloaded the models:

python .venv/bin/fetch_helixer_models.py

That placed the models in my home folder (/home/$USER/.local/share/Helixer/models). That’s not ideal because it clutters my machine, so I’ll need to remember to delete them later.

When I reran the command I got another error:

Error: helixer_post_bin not found in $PATH, this is required for Helixer.py to complete.

It looked like I was missing a required command. Searching the repository locally I couldn’t find it, but the README shows I had skipped another install step.

I needed to install HelixerPost, their Rust post-processing tool.

Since I have Rust installed, this should be straightforward:

cargo install --git https://github.com/usadellab/HelixerPost.git

On my Debian machine I also needed an additional system dependency: libhdf5-dev

sudo apt install libhdf5-dev

With that installed, I could build the post-processor.

I tried running Helixer again:

Helixer.py \
  --lineage fungi \
  --fasta-path data/GCF_003290485.1_ASM329048v1_genomic.fna.gz  \
  --species Malassezia_restricta \
  --gff-output-path data/Malassezia_restricta_helixer.gff3

This time it ran and I waited for the results. I have 16 CPU threads and Helixer used them fully, which is good since I don’t have a compatible GPU.

After just under three minutes it finished and I saw:

Total: 10585288bp across 1474 windows

Helixer successfully finished the annotation of data/GCF_003290485.1_ASM329048v1_genomic.fna.gz in 0.05 hours. GFF file written to data/Malassezia_restricta_helixer.gff3.

This is very fast, especially without a GPU.

I also tried the Docker image for comparison. The following command was created by Claude Sonnet 4.6 digesting Docker README:

docker run --rm \
  --mount type=bind,source="$(pwd)"/data,target=/home/helixer_user/shared \
  --mount type=bind,source="$HOME/.local/share/Helixer",target=/home/helixer_user/.local/share/Helixer \
  gglyptodon/helixer-docker:latest \
  Helixer.py \
    --lineage fungi \
    --fasta-path /home/helixer_user/shared/GCF_003290485.1_ASM329048v1_genomic.fna.gz \
    --species Malassezia_restricta \
    --gff-output-path /home/helixer_user/shared/Malassezia_restricta_helixer.gff3

The Docker command also launched as expected and used all CPU threads; it finished after a few minutes. So both approaches work well.

Conclusion

Overall, Helixer seems to work very well. It’s worth reading the installation instructions; even going in blind, the project provides enough guardrails to make installation relatively easy. I like that the project uses Python and Rust - sensible choices familiar to many people in bioinformatics.

One downside is that Helixer currently provides models only for fungi, plants, invertebrates, and vertebrates. The eukaryotes I’m interested in (from my PhD) are unicellular organisms that are often overlooked; they don’t fit neatly into those categories except sometimes as fungi, and are often called algae or protists, which is a larger topic by itself.

The Helixer authors suggest training custom models for these cases. That is potentially a lot of work, so I won’t attempt it today.

All in all, Helixer seems like a useful addition to the eukaryotic gene-caller toolbox.

Cleaning up

As I now installed on my machine the post processing tool, downloaded models into my home folder, and downloaded the docker image it’s worth cleaning up.

# Remove the HelixerPost binary installed via cargo
cargo uninstall helixer_post_bin

# Remove the downloaded Helixer models
rm -rf ~/.local/share/Helixer

# Remove the Docker image
docker rmi gglyptodon/helixer-docker:latest

# Finally remove the local .venv
rm -r .venv