Archive Ensembl HomeArchive Ensembl Home

Ensembl Virtual Machine

Ensembl has available for download a virtual machine pre-packaged and pre-configured the latest ensembl-api. It is a quick and simple way to get started with Ensembl.

Overview of the process

The process is described in detail in the remainder of this document, with the main steps summarised as follows.

  1. Obtain VirtualBox
  2. Download and import the virtual machine
  3. Create shared folders
  4. Start and verify the Ensembl installation

1. Obtaining VirtualBox

Virtualbox is a free and opensource virtualisation platform used to run the Ensembl Virtual Machine; it is necessary to download and install this package to run the VM (Virtual Machine). You can obtain it by visiting the VirtualBox downloads page and downloading and installing the appropriate standard virtual box platform package for your platform. 

2. Download and import the Ensembl Virtual Machine

The Ensembl Virtual Machine can be downloaded from

Once the download is complete, double click on the file which will cause VirtualBox to launch with the dialog box below; click "import" as indicated by the red arrow in the image.

This will prompt the appearance of the following dialog

Once the process has completed you should see the following window, indicating that the import was successful and the VM is in a stopped state.

Do not start the VM at this point. The next step is to configure VirtualBox to allow read/write access to folders on your host machine.

3. Configuring Shared Folders

To allow read/write access from the VM to your laptop/desktop filesystems you must configure shared folders. Configuring of shared folders must be performed whilst the VM is in a stopped state. It is a simple process and is illustrated in the image below

  1. Bring up the shared folders dialog by clicking the "Shared Folders" option in the VirtualBox control panel indicated by the "1" in the image
  2. Click the add folder icon illustrated by "2" in the image above 
  3. Toggle the "Auto-mount" option to on (shown by "3" in the image above)
  4. Click the drop down at position "4", 
  5. Click "Other..." which will bring up the file browser for your platform. Navigate to a folder you wish to share and choose it. 

You should now have a view similar to the last panel, indicating success. Click OK to dispense with the window.

4. Starting the Virtual Machine and Verifying the installation

It is trivial to start the Virtual Machine. Simply click the start button indicated by the red arrow on the control panel in the image below.

The VM will now begin to boot and you will be presented with the following display

Once completed, the Ensembl Desktop will appear with shortcuts to the ensembl-api-folder, VEP and your Shared Folders on the desktop

Verify installation

Now verify the installation, click on the terminal icon on the panel on the left, and run the following command

ensembl@ensembl:~$ ./verify-installation 

You should receive the following output to indicate success.

ensembl@ensembl:~$ ./verify-installation 

Installation is good. Connection to Ensembl works and you can query the human core database

Try the region report tool

$ cd ~/ensembl-api-folder/ensembl-tools/scripts/region_reporter/

$ perl --species=Human --chromosome=x --start=133017695 --end=133161157

Optionally verify the Variant Effect Predictor (VEP)

$ cd ~/ensembl-api-folder/VEP

$ perl ./ -i example.vcf -force