Skip to content

Running Ensembl VEP on GRCh37 Data

Oak
Aerial dusk view of two nearly mirrored glowing forests across a valley, with drifting pods lighting individual leaves in different colors.

By the end of this guide you will have a GRCh37 VCF annotated offline by Ensembl VEP, with one consequence block per variant per transcript, HGVS nomenclature, gnomAD allele frequencies, CADD scores, and dbNSFP predictor scores, plus a flat table you can load into pandas or DuckDB. You need a Linux or macOS machine with about 60 GB of free disk. You also need Docker or a Perl environment, a GRCh37 VCF, and the GRCh37 reference FASTA that VCF was called against. Everything below runs without network access once the caches are downloaded, which matters both for speed and for keeping personal genomic data off third-party servers.

1. Confirm you are really on GRCh37, and decide whether to stay there

Before installing anything, check which assembly your VCF was called against. Most consumer and clinical sequencing output from the 2010s is GRCh37. It often comes in the Broad “b37” flavour, with contigs named 1, 2 and MT. The UCSC “hg19” flavour names them chr1, chr2 and chrM. These are not interchangeable at the contig level, and hg19’s chrM uses a different mitochondrial reference sequence than GRCh37’s MT.

The VCF header usually tells you. Look at the contig lengths, which are assembly-specific.

bcftools view -h sample.vcf.gz | grep -m5 '^##contig'

Chromosome 1 with length=249250621 is GRCh37. Chromosome 1 with length=248956422 is GRCh38. If the header carries no contigs, check a few known positions instead, or find the ##reference line.

Our view is that if you control the pipeline, you should realign or at least lift over to GRCh38 and annotate there. The GRCh37 gene set in Ensembl is an archive and no longer tracks the current annotation, so novel transcripts, corrected exon boundaries and MANE Select designations are unavailable. Even so, staying on GRCh37 is the right call in two cases. The first is when you need to compare against a large legacy cohort called on the same assembly. The second is when the resource you care about exists only for GRCh37, such as an old clinical panel or a specific annotation file. Lifting over introduces its own errors, including strand flips and dropped variants in regions the chain file does not map. Annotating twice, once on each assembly, is cheap and tells you which differences are real.

2. Install VEP

Use the container. VEP has a long Perl dependency chain (Bio::DB::HTS, DBI, Set::IntervalTree) and building it by hand is the most common way to lose an afternoon.

docker pull ensemblorg/ensembl-vep:release_113.0
mkdir -p $HOME/vep_data && chmod a+rwx $HOME/vep_data

Pin the release tag rather than using latest. Annotation output changes between VEP versions, and a reproducible analysis needs a fixed version pinned alongside a fixed cache version. This is the same discipline that pipeline frameworks enforce by construction, and it is one reason Nextflow-based annotation workflows have become the default for reproducible variant annotation and ranking 1.

If you prefer a native install, use the Ensembl installer inside a conda environment:

conda create -n vep -c bioconda -c conda-forge ensembl-vep=113.0
conda activate vep

The conda build ships vep, filter_vep and haplo, along with the INSTALL.pl script used to fetch caches and plugins.

3. Download the GRCh37 cache and a bgzipped reference FASTA

VEP’s offline mode reads a preprocessed cache directory rather than querying the Ensembl database. There is a separate cache per assembly, and GRCh37 caches are built and published for every release even though the underlying gene set is archival.

docker run -it --rm -v $HOME/vep_data:/data ensemblorg/ensembl-vep:release_113.0 \
  perl INSTALL.pl \
    --AUTO cf \
    --SPECIES homo_sapiens \
    --ASSEMBLY GRCh37 \
    --CACHEDIR /data \
    --CACHE_VERSION 113

--AUTO cf fetches the cache (c) and the FASTA (f) without reinstalling the API. You end up with /data/homo_sapiens/113_GRCh37/ and a FASTA named Homo_sapiens.GRCh37.75.dna.primary_assembly.fa.gz. Note the 75 in that filename: the GRCh37 sequence and gene set are frozen at that Ensembl release, which is exactly the archival behaviour described above.

Three cache flavours exist, and the choice affects every downstream transcript ID.

  • The default Ensembl cache uses Ensembl/GENCODE transcripts (ENST...).
  • The RefSeq cache (homo_sapiens_refseq_vep_113_GRCh37) uses NM_... transcripts, which most clinical reports quote.
  • The merged cache (homo_sapiens_merged_vep_113_GRCh37) contains both, and requires --merged on the command line.

We recommend the merged cache for personal genome work. You get Ensembl transcripts for internal consistency and RefSeq transcripts for cross-referencing published variant literature, at the cost of roughly doubled output rows per variant. Add --refseq instead if you only want NM_ accessions.

The FASTA must be bgzip-compressed and faidx-indexed for VEP to use it with --hgvs. The installer handles this. If you supply your own, prepare it explicitly:

bgzip -c hg19.fa > hg19.fa.gz
samtools faidx hg19.fa.gz    # produces .fai and .gzi

A plain gzip file will fail with an unhelpful error about random access.

4. Normalize the VCF before annotating

VEP’s consequence calls depend on the exact representation of an indel. Left-aligning and splitting multi-allelic sites first removes a whole class of discrepancies, and it makes joins against gnomAD and CADD behave.

bcftools norm -m -any -f hg19.fa sample.vcf.gz -Ou \
| bcftools norm -f hg19.fa -d exact -Oz -o sample.norm.vcf.gz
bcftools index -t sample.norm.vcf.gz

-m -any splits multi-allelic records into one ALT per line. The second bcftools norm call left-aligns against the reference and drops exact duplicates. Watch the stderr summary: if bcftools reports a large number of records where REF does not match the reference base, your VCF and your FASTA are from different assemblies or different contig flavours. Fix that before continuing rather than filtering the mismatches away.

If your VCF uses chr-prefixed contigs and your cache does not, rename rather than re-call.

bcftools annotate --rename-chrs chr_to_ens.txt sample.norm.vcf.gz -Oz -o sample.ens.vcf.gz

chr_to_ens.txt is two whitespace-separated columns, old name then new name, with one pair per line. Map chrM to MT only if you are confident the mitochondrial sequences match. VEP also accepts --chr_prefix-free input transparently in many cases, but explicit renaming keeps the custom annotation files in step.

5. Run VEP offline on GRCh37

This is the core command. Every flag here earns its place.

docker run --rm -v $HOME/vep_data:/data -v $PWD:/work \
  ensemblorg/ensembl-vep:release_113.0 vep \
    --input_file /work/sample.ens.vcf.gz \
    --output_file /work/sample.vep.vcf.gz \
    --vcf --compress_output bgzip \
    --cache --offline --merged \
    --dir_cache /data --cache_version 113 \
    --assembly GRCh37 \
    --fasta /data/homo_sapiens/113_GRCh37/Homo_sapiens.GRCh37.75.dna.primary_assembly.fa.gz \
    --species homo_sapiens \
    --symbol --biotype --canonical --protein --numbers --domains \
    --hgvs --hgvsg --shift_hgvs 1 \
    --check_existing --af --af_gnomade \
    --variant_class --sift b --polyphen b \
    --total_length --allele_number \
    --fork 4 --buffer_size 20000 \
    --stats_file /work/sample.vep.html

--offline is what makes this deterministic. It forbids any database lookup and fails loudly if you request a feature the cache cannot serve, which is much better than silently degrading.

--assembly GRCh37 is required whenever more than one assembly cache is present in --dir_cache. Without it, VEP will either pick the only cache it finds or exit with an ambiguity error. Setting it explicitly is cheap insurance.

--hgvs needs --fasta in offline mode, because HGVS notation depends on reference sequence context that the cache does not store. --shift_hgvs 1 applies the 3’ shifting rule for indels in repetitive sequence, which is what HGVS requires and what variant databases expect.

--af_gnomade pulls gnomAD exome allele frequencies stored in the cache. Do not confuse it with --af_gnomadg, which covers gnomAD genomes and is not available in the GRCh37 cache. For genome frequencies on GRCh37 you need a custom annotation, covered next.

Skip --everything. It is a convenience alias that turns on flags you probably do not want on GRCh37, including --mane, which yields nothing because MANE Select is defined on GRCh38. Enumerating flags keeps the CSQ field narrow and the output readable.

Use --fork 4 to match physical cores and raise --buffer_size to 20000 for whole-genome input. Memory scales with buffer size times fork count, so a 32 GB machine handles those numbers comfortably while 100000 will not.

6. Add gnomAD genomes, CADD, dbNSFP, and LOFTEE

Custom annotation and plugins are where GRCh37 work gets fiddly, because every resource must be the GRCh37 build. Mixing builds produces annotations that look plausible and are wrong.

gnomAD v2.1.1 is natively GRCh37, which is one of the few advantages of staying on this assembly. Download the sites VCFs and attach them with --custom:

--custom file=/data/gnomad.genomes.r2.1.1.sites.vcf.bgz,short_name=gnomADg,\
format=vcf,type=exact,coords=0,fields=AF%AF_popmax%nhomalt

type=exact requires allele-level matching rather than positional overlap, which is what you want for frequency. coords=0 tells VEP the file uses Ensembl-style contig names without chr.

CADD v1.6 publishes GRCh37 files. Index them with tabix and point the plugin at both SNV and indel files:

--plugin CADD,snv=/data/whole_genome_SNVs.tsv.gz,indels=/data/InDels.tsv.gz

dbNSFP ships sorted by GRCh38 coordinates. For GRCh37 you must re-sort by the hg19 columns (8 and 9 in dbNSFP 4.x) and re-index, otherwise tabix lookups return nothing at all:

zcat dbNSFP4.7a_variant.chr*.gz \
| awk 'BEGIN{FS=OFS="\t"} $8 != "." ' \
| sort -k8,8 -k9,9n \
| bgzip -c > dbNSFP4.7a_grch37.gz
tabix -s 8 -b 9 -e 9 dbNSFP4.7a_grch37.gz

Then add the header line back as dbNSFP’s own README instructs, and call the plugin with the fields you want rather than ALL:

--plugin dbNSFP,/data/dbNSFP4.7a_grch37.gz,REVEL_score,CADD_phred,MetaSVM_pred,gnomAD_exomes_AF

LOFTEE, which flags predicted loss-of-function variants as high or low confidence, has separate GRCh37 and GRCh38 code paths. Use the GRCh37 branch of the repository with the GRCh37 ancestral sequence and conservation database:

--plugin LoF,loftee_path:/data/loftee,\
human_ancestor_fa:/data/human_ancestor.fa.gz,\
conservation_file:/data/phylocsf_gerp.sql

A silent failure mode here is running the GRCh38 LOFTEE code against GRCh37 input. It will emit LoF annotations that are meaningless. Verify by checking a known LoF variant with a published call.

7. Reduce to one consequence per variant and filter

A merged-cache whole-genome run produces several million CSQ entries. For most analyses you want a single representative consequence per variant, plus the full set retained for anything you follow up.

Add --flag_pick_allele_gene to the main run. It keeps every transcript annotation and marks one per allele per gene with PICK=1, which is safer than --pick, which discards the rest. The selection order is configurable with --pick_order, and on GRCh37 we set it to canonical,biotype,rank,ccds,length because MANE is unavailable.

Convert the annotated VCF into a table with bcftools +split-vep:

bcftools +split-vep sample.vep.vcf.gz \
  -f '%CHROM\t%POS\t%REF\t%ALT\t%SYMBOL\t%Consequence\t%IMPACT\t%HGVSc\t%HGVSp\t%gnomADg_AF\t%CADD_PHRED\n' \
  -d -i 'PICK=1' -A tab > sample.vep.tsv

Or filter within VEP’s own language, which handles the nested CSQ structure directly:

filter_vep -i sample.vep.vcf.gz -o rare_lof.vcf \
  --filter "IMPACT is HIGH and (gnomADg_AF < 0.001 or not gnomADg_AF)"

The not gnomADg_AF clause matters. A variant absent from gnomAD has no AF field, and a naive numeric comparison silently drops exactly the rare variants you were looking for. This kind of missing-field handling is one of the recurring sources of error in exome annotation pipelines, and it is worth unit-testing against a few known variants 2.

If you need MAF format for downstream somatic tooling, vcf2maf wraps VEP and emits per-variant MAF rows. It is a Perl script that re-runs VEP internally and is slow on large inputs. A Rust reimplementation now exists that reads an already-annotated VCF and converts it far faster 3.

Nothing in this output is a clinical result. Pathogenicity predictors like REVEL and CADD are population-trained scores, not diagnoses, and any variant you intend to act on needs review by a clinical geneticist working from a validated assay.

8. Sanity-check the annotations

Never trust a first VEP run. Three checks catch nearly every configuration error.

First, read the HTML stats file. The consequence distribution should be dominated by intronic and intergenic variants for a whole genome. If intergenic_variant is above roughly 80 percent, your coordinates are probably off by an assembly.

Second, take five variants with published HGVS notation from ClinVar’s GRCh37 VCF and confirm VEP reproduces the same HGVSc string on the same transcript. Discrepancies usually trace to --shift_hgvs or to a transcript version mismatch between cache and source.

Third, count how many variants received a gnomADg_AF value. For a European-ancestry genome, the large majority of common variants should match gnomAD. A near-zero match rate means contig naming or coords is wrong in the --custom string.

Common problems

“ERROR: Cache directory does not contain assembly GRCh37” means --dir_cache points at the wrong directory or the cache version does not match --cache_version. List $HOME/vep_data/homo_sapiens/ and use the directory name verbatim.

Annotations come back empty for every variant. This is almost always a contig naming mismatch between input and cache. Ensembl caches use 1, not chr1. Rename with bcftools annotate --rename-chrs.

HGVS fields are blank. Offline HGVS requires --fasta with a bgzipped, indexed FASTA. Check for both .fai and .gzi beside the .fa.gz.

A tabix-indexed plugin file returns nothing. Confirm the file is sorted on the same columns you indexed, and that the contigs inside match the input. dbNSFP on GRCh37 is the usual offender.

The run uses far more memory than expected. Lower --buffer_size before lowering --fork. Buffer size multiplies across forks.

Output rows explode after adding the merged cache. This is expected, since each variant now carries both Ensembl and RefSeq transcripts. Use --flag_pick_allele_gene and filter on PICK=1 for summary tables while retaining the full VCF.

Two runs give different results. Pin the VEP release tag, the cache version, and the version of every plugin data file. Record them alongside the output. Workflow managers make this a property of the pipeline rather than a habit 1.

Footnotes

  1. D. Scognamiglio, E. Bonetti, A. Moroni, et al. MuSA: a Nextflow pipeline for deep, reproducible annotation and clinical ranking of genomic variants. BMC Bioinformatics, 2026. https://doi.org/10.1186/s12859-026-06513-0 ↩ ↩2

  2. Karthikasri Karuppusamy, Shobana Sundar. A Comprehensive Integrated Pipeline for Detection and Annotation of Variants in Whole Exome Sequencing Data. Molecular Biotechnology, 2026. https://doi.org/10.1007/s12033-026-01599-6 ↩

  3. Robert Allaway. mafsmith: a Rust reimplementation of vcf2maf. 2026. https://doi.org/10.64898/2026.05.12.724685 ↩

Pothos builds longitudinal molecular profiles of individuals: whole-genome sequencing, single-cell RNA sequencing, and plasma proteomics, delivered as a detailed report, every data file, and stored cells. Build your profile.