fastVEP

A high-performance Variant Effect Predictor written in Rust. fastVEP predicts the functional consequences of genomic variants (SNPs, insertions, deletions, structural variants) on genes, transcripts, and protein sequences, with direct integration of clinical and population databases.

fastVEP is inspired by and aims to be compatible with Ensembl VEP and Illumina Nirvana, while delivering significantly better performance through Rust's zero-cost abstractions and native parallelism.

Try it now: A hosted web server is available at fastVEP.org — paste VCF data and get annotated results instantly, no installation required.

Features

• Variant Consequence Prediction — Classifies variants using 49 Sequence Ontology terms (missense, frameshift, splice donor, copy_number_change, transcript_ablation, etc.)
• Structural Variant Support — Full SV pipeline: <DEL>, <DUP>, <INV>, <CNV>, <BND>, <INS>, <STR> with SV-specific consequence prediction
• Supplementary Annotations — Direct integration with ClinVar, gnomAD, dbSNP, COSMIC, 1000 Genomes, TOPMed, MitoMap via the native fastSA format (v1: zstd block compression with byte-budgeted block cache; v2: echtvar-inspired chunked ZIP with Var32 encoding, parallel u32 value arrays, delta encoding, and LRU caching)
• Prediction Scores — PhyloP, GERP, REVEL, SpliceAI, PrimateAI, DANN conservation and pathogenicity scores; SIFT/PolyPhen via dbNSFP
• Gene-Level Annotations — OMIM phenotypes, gnomAD gene constraint (pLI, LOEUF), ClinGen gene-disease validity
• Filter Engine — Expression-based filtering compatible with VEP's filter_vep syntax
• HGVS Nomenclature — Generates HGVSg, HGVSc, and HGVSp notations with 3' normalization
• Multiple Output Formats — VCF (with 49-field CSQ), tab-delimited, JSON (including Nirvana-style structured output)
• Multi-Sample Support — Parse FORMAT/GT/DP/GQ/AD fields per sample with genotype classification
• Regulatory Region Detection — Promoters, enhancers, CTCF binding sites, TF binding sites from Ensembl regulatory build
• Mitochondrial Support — Circular coordinate handling, vertebrate mitochondrial codon table (NCBI table 2)
• Custom Annotations — User-provided VCF (--source custom_vcf) and BED (--source custom_bed) files; .osi interval databases load alongside .osa via --sa-dir
• ACMG-AMP Classification — --acmg runs the full Richards 2015 + ClinGen SVI rule set (28 criteria, configurable thresholds, trio / compound-het support via --proband/--mother/--father)
• VEP --merged Cache — --gff3 is repeatable on annotate and cache; combine Ensembl + RefSeq in a single run with per-transcript SOURCE labels
• --sa-only Mode — Skip the default CSQ pipeline and emit only supplementary annotations, useful for re-annotating already-annotated VCFs
• Gzipped VCF Input — annotate auto-detects .vcf.gz / .vcf.bgz (no upstream decompression needed)
• Web Interface — Built-in web GUI for interactive variant annotation
• GFF3 Annotation Support — Load gene models from standard GFF3 files (any organism)

Quick Start

1. Install Rust (if you don't have it)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

2. Build and install fastVEP

git clone https://github.com/Huang-lab/fastVEP.git
cd fastVEP

# Build and install both binaries to ~/.cargo/bin/
cargo install --path crates/fastvep-cli   # fastvep (CLI annotator)
cargo install --path crates/fastvep-web   # fastvep-web (production web server)

# Verify it works
fastvep --version

Note: cargo install places the binary in ~/.cargo/bin/. If fastvep is not found after install, run source "$HOME/.cargo/env" or add this line to your ~/.zshrc (or ~/.bashrc): bash source "$HOME/.cargo/env"

Alternative: build a conda package

Prefer conda? The repo ships a recipe under conda/recipe/ that builds both fastvep and fastvep-web into a local conda package (Linux and macOS):

# One-time: tools for building conda packages
conda install -n base -c conda-forge conda-build

# Build the package from the repo root
conda build conda/recipe

# Install into a fresh environment
conda create -n fastvep -c local fastvep
conda activate fastvep
fastvep --version

3. Try it — annotate the included test data

fastVEP ships with a small test VCF and GFF3 so you can try it immediately:

# Annotate 12 test variants covering SNVs, indels, splice sites, UTRs, and intergenic regions
fastvep annotate -i tests/test.vcf --gff3 tests/test.gff3 --hgvs --output-format tab

4. Build supplementary annotation databases

# Build ClinVar annotation database
fastvep sa-build --source clinvar --input clinvar.vcf.gz --output clinvar

# Build gnomAD population frequency database
fastvep sa-build --source gnomad --input gnomad.genomes.v4.vcf.bgz --output gnomad

# Build PhyloP conservation scores
fastvep sa-build --source phylop --input hg38.phyloP100way.wigFix.gz --output phylop

# Build SpliceAI predictions
fastvep sa-build --source spliceai --input spliceai_scores.vcf.gz --output spliceai

5. Annotate with supplementary databases

# Annotate with all databases in a directory
fastvep annotate \
  -i your_variants.vcf \
  -o annotated.vcf \
  --gff3 Homo_sapiens.GRCh38.112.gff3 \
  --fasta Homo_sapiens.GRCh38.dna.primary_assembly.fa \
  --sa-dir /path/to/annotation_databases/ \
  --hgvs

6. Filter annotated variants

# Filter for high-impact or rare missense variants
fastvep filter \
  -i annotated.vcf \
  --filter "IMPACT is HIGH or (Consequence in missense_variant and AF < 0.001)"

7. Launch the web interface

# Quick start — uses a built-in example gene model (OR4F5, chr1)
fastvep-web

# With your own data
fastvep-web --gff3 Homo_sapiens.GRCh38.115.gff3 --fasta Homo_sapiens.GRCh38.dna.primary_assembly.fa

# With supplementary annotations (ClinVar, gnomAD, etc.)
fastvep-web --gff3 genes.gff3 --fasta ref.fa --sa-dir /path/to/sa_databases/

Open http://localhost:8080 in your browser. The web interface lets you paste VCF data, switch gene models, and view results in an interactive table.

Note: fastvep-web is a separate production-quality binary (axum/tokio, async, multi-connection). The legacy fastvep web command still works but is single-threaded.

Local Setup Guide

This section walks through setting up fastVEP with full annotation capabilities (gene models, reference sequence, and supplementary databases like ClinVar and gnomAD).

Step 1: Download reference data

mkdir -p data && cd data

# Gene models (GFF3) — pick your organism
# Human GRCh38
wget https://ftp.ensembl.org/pub/release-115/gff3/homo_sapiens/Homo_sapiens.GRCh38.115.gff3.gz
gunzip Homo_sapiens.GRCh38.115.gff3.gz

# Reference FASTA (needed for HGVS and sequence context)
wget https://ftp.ensembl.org/pub/release-115/fasta/homo_sapiens/dna/Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz
gunzip Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz

# Create FASTA index (enables memory-mapped access — important for large genomes)
samtools faidx Homo_sapiens.GRCh38.dna.primary_assembly.fa

Step 2: Build supplementary annotation databases

Each supplementary database (ClinVar, gnomAD, etc.) is built in two steps — download the source file, then run fastvep sa-build to convert it into the fastSA .osa + .osa.idx pair. sa-build is a converter, not a downloader; if you skip the download, the resulting .osa will be empty and your annotations will silently come back blank. After each build, check that the .osa size matches the expected magnitude (column below); a few-KB .osa is the tell that the source file wasn't real.

mkdir -p sa_databases

# ── ClinVar — clinical variant significance ──
# Download (~50 MB)
wget https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz
# Build (expect ~80–120 MB .osa)
fastvep sa-build --source clinvar -i clinvar.vcf.gz -o sa_databases/clinvar --assembly GRCh38

# ── gnomAD v4 — population allele frequencies ──
# Download per-chromosome from https://gnomad.broadinstitute.org/downloads
# (~30–60 GB total for genomes v4.0)
fastvep sa-build --source gnomad -i gnomad.genomes.v4.0.sites.vcf.bgz -o sa_databases/gnomad --assembly GRCh38

# ── dbSNP — variant identifiers ──
wget https://ftp.ncbi.nih.gov/snp/latest_release/VCF/GCF_000001405.40.gz
fastvep sa-build --source dbsnp -i GCF_000001405.40.gz -o sa_databases/dbsnp --assembly GRCh38

# ── COSMIC — somatic mutations (requires license) ──
# https://cancer.sanger.ac.uk/cosmic/download
fastvep sa-build --source cosmic -i CosmicCodingMuts.vcf.gz -o sa_databases/cosmic --assembly GRCh38

Verify before moving on:

ls -la sa_databases/*.osa
# Expected: clinvar ~100 MB; gnomad several GB; dbsnp ~5 GB.
# Anything < 1 MB usually means an empty build — re-check the source file.

For ACMG-AMP classification specifically (REVEL, SpliceAI, PhyloP, dbNSFP, OMIM, ClinVar protein index, etc.), see the dedicated ACMG Setup Guide — it walks through every source the classifier needs with download URLs, build commands, expected disk sizes, and a verification recipe.

Step 3: Run the CLI annotator

fastvep annotate \
  -i your_variants.vcf \
  -o annotated.vcf \
  --gff3 data/Homo_sapiens.GRCh38.115.gff3 \
  --fasta data/Homo_sapiens.GRCh38.dna.primary_assembly.fa \
  --sa-dir sa_databases/ \
  --hgvs

Step 4: Run the web server

# Install the web server binary
cargo install --path crates/fastvep-web

# Run with all annotation sources
fastvep-web \
  --gff3 data/Homo_sapiens.GRCh38.115.gff3 \
  --fasta data/Homo_sapiens.GRCh38.dna.primary_assembly.fa \
  --sa-dir sa_databases/ \
  --port 8080

All flags also accept environment variables (FASTVEP_GFF3, FASTVEP_FASTA, FASTVEP_SA_DIR, FASTVEP_PORT) for container deployments.

Multi-organism setup

To serve multiple genomes from the web interface, organize data into subdirectories and use --data-dir. Each subdirectory is one genome — the server auto-detects GFF3, FASTA, and SA files inside.

Directory layout:

genomes/
  human_grch38/
    Homo_sapiens.GRCh38.115.gff3       # gene models (required)
    Homo_sapiens.GRCh38.dna.primary_assembly.fa   # reference (optional, for HGVS)
    Homo_sapiens.GRCh38.dna.primary_assembly.fa.fai
    sa/                                 # supplementary annotations (optional)
      clinvar.osa2
      gnomad.osa2
      dbsnp.osa2
  mouse_grcm39/
    Mus_musculus.GRCm39.115.gff3
    mouse.fa
    mouse.fa.fai
  zebrafish/
    Danio_rerio.GRCz11.115.gff3

Setup:

mkdir -p genomes/human_grch38/sa genomes/mouse_grcm39 genomes/zebrafish

# Human: GFF3 + FASTA + SA databases
cp data/Homo_sapiens.GRCh38.115.gff3 genomes/human_grch38/
cp data/Homo_sapiens.GRCh38.dna.primary_assembly.fa* genomes/human_grch38/
cp sa_databases/*.osa2 genomes/human_grch38/sa/   # ClinVar, gnomAD, etc.

# Mouse
wget -O- https://ftp.ensembl.org/pub/release-115/gff3/mus_musculus/Mus_musculus.GRCm39.115.gff3.gz | gunzip > genomes/mouse_grcm39/Mus_musculus.GRCm39.115.gff3

# Zebrafish
wget -O- https://ftp.ensembl.org/pub/release-115/gff3/danio_rerio/Danio_rerio.GRCz11.115.gff3.gz | gunzip > genomes/zebrafish/Danio_rerio.GRCz11.115.gff3

Run:

fastvep-web --data-dir genomes/

Users can switch between organisms from the dropdown in the web UI. When a genome has a sa/ subdirectory, its SA databases are automatically loaded. The dropdown shows "(FASTA + SA)" labels for genomes that have these resources.

--sa-dir is optional — if provided, it serves as a fallback for genomes that don't have their own sa/ folder. If the directory doesn't exist, the server starts without SA (no error).

fastVEP works with any organism — just provide the matching GFF3 (and optionally FASTA for HGVS).

Merged annotation (Ensembl + RefSeq, à la VEP --merged)

--gff3 accepts multiple values, so a single run can annotate against Ensembl and RefSeq side-by-side — fastVEP's analog of VEP's --merged cache. The SOURCE column of each CSQ entry records which file produced that transcript.

# Auto-detected SOURCE labels (filename contains "ensembl"/"gencode" → Ensembl;
# "refseq" or GCF_ prefix → RefSeq; otherwise the basename).
fastvep annotate -i variants.vcf \
  --gff3 Homo_sapiens.GRCh38.115.gff3 \
  --gff3 GCF_000001405.40.gff.gz \
  --fasta GRCh38.fa --hgvs

# Or set the labels explicitly with `LABEL=path` (also accepts comma-separated):
fastvep annotate -i variants.vcf \
  --gff3 Ensembl=ensembl.gff3,RefSeq=refseq.gff3 \
  --fasta GRCh38.fa

Each transcript carries its source through to all output formats: SOURCE field in the VCF CSQ string, the source key in JSON, and the SOURCE column in tab output (with --canonical / extended fields). Transcripts from both sources are queried independently — overlap detection, HGVS, and supplementary annotation all run per-transcript, so RefSeq NM_… and Ensembl ENST… records appear as separate CSQ entries for the same variant.

The auto-managed sidecar cache (<gff3>.fastvep.cache) only kicks in for single-GFF3 runs. For merged workflows, pre-build a combined binary cache with fastvep cache --gff3 ensembl.gff3 -o combined.cache once per source and pass --transcript-cache combined.cache on subsequent runs — though GFF3 parsing is fast enough that this is rarely needed.

Supplementary Annotation Sources

fastVEP supports direct integration with clinical and population databases through its native fastSA binary format. Build once with fastvep sa-build, then use --sa-dir to annotate:

| So