ensembl-vep annotates variants, and documents its own broken cases

Three tools in one package, not just the annotator

The package is more than the variant annotator. VEP, the Variant Effect Predictor, predicts the functional effects of genomic variants. Haplosaurus uses phased genotype data to predict whole-transcript haplotype sequences, which is a different question and needs a different data source. The Variant Recoder translates between different variant encodings, which is a utility rather than an analysis, and it matters more than it sounds because the same variant can be written in several equivalent ways and a pipeline that joins on variant identifiers needs them reconciled. The three are documented in separate sections of the README with their own usage, output and, for Haplosaurus, a REST interface and a flags list. The audience is genomic data engineers and anyone who has to turn a VCF into something with consequences attached, and the reason to use the package rather than a web service is the same reason you would use any command line tool: it runs on your own data.

Installing means Perl, a compiler and an installer script

The requirements are specific and modest. The VEP package needs gcc, g++ and make, and Perl, with 5.22 recommended and tested on 5.22, 5.26, 5.32, 5.34 and 5.38, plus the Perl libraries Archive::Zip and DBI. The rest of the dependencies come from the bundled installer.

git clone https://github.com/Ensembl/ensembl-vep.git
cd ensembl-vep
perl INSTALL.pl

Re-running INSTALL.pl also checks for updates to this and the co-dependent packages, which is the simplest update path the project offers. The optional modules are worth reading, because each one enables a specific capability. DBD::mysql is required for database access with `--database` or `--cache` without `--offline`. Set::IntervalTree is required for Haplosaurus and also speeds up VEP. JSON is required for writing JSON output. PerlIO::gzip gives faster compressed file parsing. Bio::DB::BigFile is required for reading custom annotation data from BigWig files. There is also a Docker image on Docker Hub published as `ensemblorg/ensembl-vep`, and a Conda package exists that the Ensembl VEP team explicitly did not produce and does not maintain, so support questions about that install will not be answered by them.

Offline mode and the cache are the operational core

The usage line in the README is short.

./vep -i input.vcf -o out.txt -offline

That `-offline` flag is the one that matters for a restricted network or a large batch job, and it pairs with the `--cache` option, which the requirements section ties to the DBD::mysql module. The design is that reference data is fetched once, cached locally, and then every subsequent run reads from the cache instead of reaching Ensembl. That is the difference between annotating one VCF interactively and annotating thousands overnight. The requirement that `--database` and `--cache` without `--offline` need a database driver reflects the same split, since the online path queries the live Ensembl services. The repository layout supports this picture, with a `modules/` directory for the Perl code, a `filter_vep` script, a `haplo` directory for Haplosaurus, a `variant_recoder` directory, and a `nextflow/` directory alongside a top-level `main.nf` pipeline definition.

The known-bugs list is the most useful part of the README

Most projects would not publish this. Ensembl VEP does, and the list explains that while the team prefer to fix all bugs, some involve code that is fundamental, and any changes have potentially far reaching impacts and require extensive testing, so the list details issues they may not resolve for some time. The first entry is the one most likely to bite you: using `--hgvs` and `--no_stats` together with multi-allelic variants may produce incorrect CDS and protein positions, or crash the tool. The workarounds are to separate multi-allelic variants onto individual input lines, and not to combine the two options. Variants overlapping exon and intron boundaries can occasionally be annotated with incorrect consequences, and there is no effective workaround for that one. Variants overlapping incomplete terminal codons may produce unreliable consequences, because those transcripts were annotated from protein fragments with incomplete open reading frames, and the recommendation is to use a more complete transcript where possible.

Minor allele frequency filtering is the one to work around properly

The MAF filtering bug is worth separating out, because the workaround changes your pipeline. Using `--freq_freq`, `--freq_gt_lt` and `--freq_filter` to filter VEP output can lead to some variants being incorrectly excluded or included, depending on the parameters. It affects only insertions and deletions, and it is caused by an allele matching issue that the team is still assessing. The recommended workaround is not to filter while running VEP and instead use the `filter_vep` script on the output files, on the grounds that in almost all circumstances this is the better approach because you retain marginal cases in the unfiltered file that may be relevant. The same bug affects the MAF filtering options on the web version. There is a further known issue where non-coding transcripts do not get their allele shifted when `--shift_3prime` is enabled, which has consequences for custom annotation features using the `type=exact` option. The `filter_vep` script in the repository root is therefore not an optional extra; for anything involving indels it is part of a correct workflow.

Reference data, releases and what the package does not decide

The repository ships ten example VCF files covering nine species and assemblies, which is a useful way to try the tool without arranging data yourself: `homo_sapiens_GRCh37.vcf` and `homo_sapiens_GRCh38.vcf`, plus `arabidopsis_thaliana_TAIR10`, `bos_taurus_UMD3.1`, `canis_familiaris_CanFam3.1`, `danio_rerio_GRCz10`, `drosophila_melanogaster_BDGP6`, `mus_musculus_GRCm38` and `rattus_norvegicus_Rnor_6.0`, and `sus_scrofa_Sscrofa10.2`. The default branch is `release/116`, and the listed releases are release/116.3, release/116.2 and release/116.1, so the package is versioned alongside the Ensembl release it annotates for. That coupling is the tool's main constraint. The consequences it predicts are defined by Ensembl's transcript models, and if your workflow depends on a different annotation set, or on the output being stable across Ensembl releases, you have to manage that yourself. The licence is Apache 2.0, and the project asks users to cite the most recent publication, McLaren and colleagues in Genome Biology 2016, to help fund ongoing development. Bug reports go to Ensembl or to a GitHub issue.

Editorial conclusion

Adopt ensembl-vep if you need variant consequence annotation across many transcripts, a cache so you are not re-fetching reference data on every run, and offline operation on a restricted network. Skip it if you need more than Ensembl's transcript set, since the annotations follow Ensembl's models and nothing else, and skip it if annotation correctness on edge cases is non-negotiable without the work to check it. Before you commit, read the known-bugs section, because the multiallelic and minor allele frequency issues have workarounds that change how you should run the tool.

Frequently asked questions

Official sources

1. Ensembl/ensembl-vep on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases