EnsemblEnsembl Home

Variant Effect Predictor Download and install


Important notice to VEP users
  • VEP is now available as the ensembl-vep package from GitHub
  • The old version available as part of ensembl-tools has been retired

Download

Use git to download the ensembl-vep package:

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

Then follow the installation instructions.

Users without the git utility installed may download a zip file from GitHub, though we would always recommend using git if possible.

curl -L -O https://github.com/Ensembl/ensembl-vep/archive/release/90.zip
unzip 90.zip
cd ensembl-vep-release-90/

To update from a previous version:

cd ensembl-vep
git pull
git checkout release/90
perl INSTALL.pl

To use an older version (this example shows how to set up release 87):

cd ensembl-vep
git checkout release/87
perl INSTALL.pl

Previous versions (ensembl-tools)

Previously VEP was available as part of the ensembl-tools package (see the Ensembl archive site for documentation). The following downloads are available for archival purposes. [Show]


What's new

New in version 90 (August 2017)

Previous version history: Show


Requirements

VEP requires Perl (>=5.10 recommended, tested on 5.8, 5.10, 5.14, 5.18, 5.22) and the DBI and DBD::mysql package installed; see this guide for more information on how to install perl modules.

VEP's INSTALL.pl script will install required components of Ensembl API for you, but VEP may also be used with any pre-existing API installations you have provided their versions match the version of VEP you are using.

VEP has been developed for UNIX-like environments and works well on Linux (e.g. Ubuntu, Debian, Mint) and Mac OSX. It can also be used on Windows systems with a more involved installation process.


Installation

VEP's INSTALL.pl makes it easy to set up your environment for using the VEP. It will download and configure a minimal set of the Ensembl API for use by the VEP, and can also download cache files, FASTA files and plugins.

Run the following, and follow any prompts as they appear:

perl INSTALL.pl

Additional non-essential components and enhancements must be installed manually.

Software components installed

Users who already have the latest version of the API installed do not need to run the script, although may find it useful for getting an up-to-date API install (with post-release patches applied), and for retrieving cache and FASTA files. The API set installed by the script is local to the VEP, and will not affect any other Ensembl API installations.

The script will also attempt to install a Perl::XS module, Bio::DB::HTS, for rapid access to bgzipped FASTA files. If this fails, you may add the --NO_HTSLIB flag when running the installer; VEP will fall back to using Bio::DB::Fasta for this functionality (more details).

Running the installer

The installer script is run on the command line as follows:

 perl INSTALL.pl [options] 

Users then follow on-screen prompts. Please heed any warnings, as when the script says it will delete/overwrite something, it really will!

Most users should not need to add any options, but configuration of the installer is possible with the following flags:

Flag Alternate Description
--AUTO
-a
Run installer without user prompts. Use "a" (API + Bio::DB::HTS/htslib), "l" (Bio::DB::HTS/htslib only), "c" (cache), "f" (FASTA), "p" (plugins) to specify parts to install e.g. -a ac for API and cache
--SPECIES
-s
Comma-separated list of species to install when using --AUTO. To install the RefSeq cache, add "_refseq" to the species name, e.g. "homo_sapiens_refseq", or "_merged" to install the merged Ensembl/RefSeq cache. Remember to use --refseq or --merged when running the VEP with the relevant cache!
--ASSEMBLY
-y
Assembly version to use when using --AUTO. Most species have only one assembly available on each software release; currently this is only required for human on release 76 onwards.
--PLUGINS
-g
Comma-separated list of plugins to install when using --AUTO. To install all available plugins, use "--PLUGINS all". To list available plugins, use "perl INSTALL.pl -a p --PLUGINS list".
--VERSION [version]
-v
By default the script will install the latest version of the Ensembl API (currently 90). Users can force the script to install a different version at their own risk. This flag will also set the data version (cache, FASTA) to install unless set separately with --CACHE_VERSION.
--CACHE_VERSION [version]
  By default the script will download the latest version of VEP's caches and FASTA files (currently 90). Users can force the script to install a different version at their own risk. Use --VERSION to set the API version separately.
--DESTDIR [dir]
-d
By default the script will install the API modules in a subdirectory of the current directory named "Bio". Using this option users may configure where the Bio directory is created. If something other than the default is used, this directory must either be added to your PERL5LIB environment variable when running the VEP, or included using perl's -I flag:
perl -I [dir] vep
--CACHEDIR [dir]
-c
By default the script will install the cache files in the ".vep" subdirectory of the user's home area. Using this option users can configure where cache files are installed. The --dir flag must be passed when running the VEP if a non-default directory is given:
./vep --dir [dir]
--UPDATE
-n
Run the installer with this flag to check for and download new versions of the VEP. Any existing files are backed up. You will need to rerun the installer after update to retrieve update API, cache and FASTA files.
--QUIET
-q
Don't write any status output when using --AUTO.
--PREFER_BIN
-p
Use this if the installer fails with out of memory errors.
--NO_HTSLIB
-l
Don't attempt to install Bio::DB::HTS/htslib
--NO_TEST
  Don't run API tests - useful if you know a harmless failure will prevent continuation of the installer

Additional components

INSTALL.pl will set up the minimum requirements for VEP, and for most users this will be adequate. Some features and enhancements, however, require the installation of additional components. Most are perl modules that are easily installed using cpanm; see this guide for more information on how to install perl modules.

Typically users of cpanm will wish to install modules locally in their home directories; this shows how to set up a path for perl modules and install one there:

mkdir -p $HOME/cpanm
export PERL5LIB=$PERL5LIB:$HOME/cpanm/lib/perl5
cpanm -l $HOME/cpanm Set::IntervalTree

To make the change to PERL5LIB permanent, it is recommended to add the export line to your $HOME/.bashrc or $HOME/.profile.

Bio::DB::BigFile

In order for VEP to be able to access bigWig format custom annotation files, the Bio::DB::BigFile perl module is required. Installation involves downloading and compiling the kent source tree. The current version of the kent source tree does not work correctly with Bio::DB::BigFile, so it is necessary to install an archive version known to work (v335).

  1. Download and unpack the kent source tree
    wget https://github.com/ucscGenomeBrowser/kent/archive/v335_base.tar.gz
    tar xzf v335_base.tar.gz
  2. Set up some environment variables; these are required only temporarily for this installation process
    export KENT_SRC=$PWD/kent-335_base/src
    export MACHTYPE=$(uname -m)
    export CFLAGS="-fPIC"
    export MYSQLINC=`mysql_config --include | sed -e 's/^-I//g'`
    export MYSQLLIBS=`mysql_config --libs`
  3. Modify kent build parameters
    cd $KENT_SRC/lib
    echo 'CFLAGS="-fPIC"' > ../inc/localEnvironment.mk
  4. Build kent source
    make clean && make
    cd ../jkOwnLib
    make clean && make
    If either of these steps fail, you may have some missing dependencies. Known common missing dependencies are libpng and libssl; these may be installed, for example, with apt-get on Ubuntu. If you do not have sudo access you may have to ask your sysadmin to install any missing dependencies.
    sudo apt-get install libpng-dev libssl-dev
    On Mac OSX you may use brew; the openssl libraries also need to be symbolically linked to a different path:
    brew install libpng openssl
    cd /usr/local/include
    ln -s ../opt/openssl/include/openssl .
    cd -
  5. On some systems (e.g. Mac OSX), a compiled file is placed in a path that Bio::DB::BigFile cannot find. You can correct this with:
    ln -s $KENT_SRC/lib/x86_64/* $KENT_SRC/lib/
  6. We'll now use cpanm to install the perl module for Bio::DB::BigFile itself. See above for guidance on this. In this example we're going to install the module to a path within your home directory. In order to do this we must modify the paths that perl looks in to find modules by adding to the PERL5LIB environment module. To make this change permanent you must add the export line to your $HOME/.bashrc or $HOME/.profile.
    mkdir -p $HOME/cpanm
    export PERL5LIB=$PERL5LIB:$HOME/cpanm/lib/perl5
    cpanm -l $HOME/cpanm Bio::DB::BigFile
    If you are prompted for the path to the kent source tree, that means something didn't go right in the compilation above. Double check that $KENT_SRC/lib/jkweb.a exists and is not found instead at e.g. $KENT_SRC/lib/x86_64/jkweb.a. You may copy or link the file (and the other files in that directory) to the former path.
    ln -s $KENT_SRC/lib/x86_64/* $KENT_SRC/lib/
  7. You should now be able to successfully run the appropriate test in the VEP package:
    perl -Imodules t/AnnotationSource_File_BigWig.t

Using VEP in Windows

VEP was developed as a command-line tool, and as a Perl script its natural environment is a Linux system. However, there are several ways you can use VEP on a Windows machine.

You may also consider using VEP's web or REST interfaces.

Virtual machines

Using a virtual machine you can run a virtual Linux system in a window on your machine. There are two ways to do this:

  1. Use the Ensembl virtual machine image
  2. Use Docker

DWIMperl

DWIMperl has a Windows package that contains base requirements for setting up VEP.

  1. Download and install DWIMperl for Windows
  2. Download and unpack the zip of the ensembl-vep package
  3. Open a Command Prompt (search for Command Prompt in the Start Menu)
  4. Navigate to the directory where you unpacked the VEP package, e.g.
    cd Downloads/ensembl-vep-release-90
  5. Run INSTALL.pl with --NO_HTSLIB and --NO_TEST; you will see some warnings about the "which" command not being available (these will also appear when running VEP and can be ignored).
    perl INSTALL.pl --NO_HTSLIB --NO_TEST

Docker

Docker allows you to run applications in virtualised "containers". A docker image for VEP is available from DockerHub:

docker pull ensemblorg/ensembl-vep
docker run -t -i ensemblorg/ensembl-vep ./vep

Currently no volumes are pre-configured for the container; this is required if you wish to download data (e.g. cache files) that persists across sessions.

The following is a brief example showing how to use a directory on your local (host) machine to store cache data for VEP.

mkdir $HOME/vep_data
chmod a+rwx $HOME/vep_data    
docker run -t -i -v $HOME/vep_data:/home/vep/.vep ensemblorg/ensembl-vep perl INSTALL.pl

You will now be prompted by the installer if you wish to re-install the API. Type "n" followed by enter to skip to cache installation. You will be presented with a list of species; type the number for your species/assembly of interest and press enter. Your data will now download and unpack; this may take a while.

If you wish to retrieve HGVS annotations it is recommended to also download the FASTA file for your species. To do this, at the next prompt type "0" and press enter. You may skip the plugin installation also.

The above process may also be performed in one command; for example, to set up the cache and corresponding FASTA for human GRCh38:

docker run -t -i -v $HOME/vep_data:/home/vep/.vep ensemblorg/ensembl-vep perl INSTALL.pl -a cf -s homo_sapiens -y GRCh38

The installer has now downloaded this data to $HOME/vep_data. VEP will automatically detect caches downloaded in this folder as it is mapped to VEP's default directory within the Docker instance.

docker run -t -i -v $HOME/vep_data:/home/vep/.vep ensemblorg/ensembl-vep /bin/bash
./vep -i examples/homo_sapiens_GRCh38.vcf -cache