EnsemblEnsembl Home

Perl API Installation


All data sets in the Ensembl system are stored in relational databases (MySQL). For each of the Ensembl databases the project provides a specific Perl API. As Ensembl takes also advantage of code provided by the BioPerl project; installation of the BioPerl package is included in these instructions. The Ensembl API is compatible with Perl version 5.10.

Video Tutorial

Ensembl has produced a video tutorial about how to install the API. Its content is based on this document so you can follow both resources when performing an installation. All commands in this video can be found from the following document on our FTP site.

YouTube channel

Installation Procedure

There are two ways of installing the Perl API. You can clone it from GitHub using Git if you have that available, or you can download the files in gzipped TAR format from our FTP site. You will also need BioPerl 1.6.1 core modules (bioperl-live).

N.B. We recommend waiting until a few days after a release before downloading the new API (or re-downloading after a few days), as there may be post-release bug fixes added to the code.

  1. Create an installation directory and download the distributions:

    $ cd
    $ mkdir src
    $ cd src
    $ wget ftp://ftp.ensembl.org/pub/ensembl-api.tar.gz
    $ wget https://cpan.metacpan.org/authors/id/C/CJ/CJFIELDS/BioPerl-1.6.1.tar.gz 
  2. Unpack the downloaded files. In the Unix command line, type:

    $ tar zxvf ensembl-api.tar.gz
    $ tar zxvf BioPerl-1.6.1.tar.gz

    In Windows, you will need an unzipping utility such as 7-Zip.

  3. Set up your environment

    You have to tell Perl where to find the modules you just installed. You can do this by using the use lib clause in your script but if you want to make these modules available for all your scripts, the best way is to add them into the PERL5LIB environment variable.

    • Under bash, ksh, or any sh-derived shell:

      export PERL5LIB
    • Under csh or tcsh:

      setenv PERL5LIB ${PERL5LIB}:${HOME}/src/bioperl-1.6.1
      setenv PERL5LIB ${PERL5LIB}:${HOME}/src/ensembl/modules
      setenv PERL5LIB ${PERL5LIB}:${HOME}/src/ensembl-compara/modules
      setenv PERL5LIB ${PERL5LIB}:${HOME}/src/ensembl-variation/modules
      setenv PERL5LIB ${PERL5LIB}:${HOME}/src/ensembl-funcgen/modules
    • Under Windows (assuming you installed the APIs in C:\src\):

      set PERL5LIB=C:\src\bioperl-1.6.1;C:\src\ensembl\modules;C:\src\ensembl-compara\modules;C:\src\ensembl-variation\modules;C:\src\ensembl-funcgen\modules
    • In Perl (we do not recommend creating hard-coded dependencies in Perl scripts):

      use lib "$ENV{HOME}/src/bioperl-1.6.1";
      use lib "$ENV{HOME}/src/ensembl/modules";
      use lib "$ENV{HOME}/src/ensembl-compara/modules";
      use lib "$ENV{HOME}/src/ensembl-variation/modules";
      use lib "$ENV{HOME}/src/ensembl-funcgen/modules";

Variation genotype and frequency data

To retrieve genotype, frequency and linkage disequilibrium (LD) data for 1000 Genomes phase 3 variants, it is necessary to install a couple of extra dependencies:

  1. Bio-DB-HTS and perl module:

    cd ~/src
    git clone --branch master --depth 1 https://github.com/samtools/htslib.git
    cd htslib
    export HTSLIB_DIR=${HOME}/src/htslib/
    cd ..
    git clone https://github.com/Ensembl/Bio-DB-HTS.git
    cd Bio-DB-HTS
    perl Build.PL
    export PERL5LIB=$PERL5LIB:${HOME}/src/Bio-DB-HTS/lib:${HOME}/src/Bio-DB-HTS/blib/arch/auto/Bio/DB/HTS/:${HOME}/src/Bio-DB-HTS/blib/arch/auto/Bio/DB/HTS/Faidx
    cd ..
    cd ensembl-variation/C_code/
    cd ../../

    Set up environment; use the path output from the "make && make install" command for the PERL5LIB variable, e.g.

    export PERL5LIB
  2. ensembl-io perl modules (only if you didn't use Git Ensembl tools to install the API):

    cd ~/src
    wget https://github.com/Ensembl/ensembl-io/archive/release/88.zip
    unzip 88.zip
    mv ensembl-io-release-88 ensembl-io

    Add this to PERL5LIB.

    • Under bash, ksh, or any sh-derived shell:

      export PERL5LIB
    • Under csh or tcsh:

      setenv PERL5LIB ${PERL5LIB}:${HOME}/src/ensembl-io/modules

Debugging an Installation

Sometimes installations can go wrong. You should follow our debugging installation guide to help diagnose and resolve installation issues.

Tips for Windows and Mac Users

Ensembl can be installed on both Windows and Mac machines however installation is not as straightforward as installing on Linux. We recommend you consult our two blog posts detailing how you can install Ensembl on Windows and on OSX. The fastest way to get up and running with Ensembl on these operating systems is to use our virtual machine.