Installation

Quick Start Overview

Installing Exomiser involves four steps:

1. Check your system meets the requirements below

2. Download the Exomiser program and data files

3. Configure Exomiser to find your data files

4. Run a test analysis to confirm everything works

Software and Hardware Requirements

Exomiser is designed to run on a standard laptop or desktop computer. However, before installing make sure your computer meets these requirements:

• Operating system: Any 64-bit operating system (Windows, Linux, or macOS)

• Java: Version 21 or above. Download from https://adoptium.net if needed. To check your current version, run: java -version

• RAM (memory):

  • Exome analysis (typically ~30,000 variants): 4 GB RAM minimum

  • Genome analysis (typically ~4,400,000 variants): 8 GB RAM minimum

  • We recommend 16 GB total system RAM for comfortable general use

• Disk space: At least 100 GB free. An SSD (solid-state drive) is strongly preferred for performance.

• Internet connection: Only needed to download files. Exomiser itself runs entirely offline once installed.

Key Concepts

Before you begin, here are a few terms used throughout this guide:

• Genome assembly (hg19 / hg38): Human genome data exists in two common reference versions — hg19 (also called GRCh37) and hg38 (GRCh38). You will need to download data for whichever version your VCF file uses. If you are unsure, ask whoever generated your VCF file.

• VCF file: A standard file format containing genetic variant data. This is the input file you will analyse with Exomiser.

• application.properties: A plain text configuration file that tells Exomiser where your data files are stored and which versions to use. You will edit this file as part of setup.

• Data version (e.g. 2512): Exomiser data files are released periodically. The number refers to the year and month of release (e.g. 2512 = February 2024). Your application.properties must reference the version you downloaded.

Installation

Exomiser consists of two parts you need to download:

1. The Exomiser application (the distribution .zip file)

2. The data files (Additional``.zip`` files containing genomic and phenotype databases)

Both are available from:

• https://github.com/exomiser/Exomiser/releases/latest

• https://data.monarchinitiative.org/exomiser/latest

Windows Installation

Step 1: Install 7-Zip

Windows’ built-in zip tool cannot handle Exomiser’s large files. Download and install 7-Zip from http://www.7-zip.org before proceeding.

Step 2: Download the files Go to https://github.com/exomiser/Exomiser/releases/latest and download:

• exomiser-cli-|version|-distribution.zip (the program)

• 2512_phenotype.zip (required for all analyses)

• 2512_hg19.zip and/or 2512_hg38.zip (download whichever matches your VCF file; download both if unsure)

Step 3: Extract the program

Right-click exomiser-cli-|version|-distribution.zip and choose 7-Zip > Extract Here. This will create a folder called exomiser-cli-|version| in the same location.

Step 4: Extract the data files

Right-click each data .zip file (e.g. 2512_phenotype.zip, 2512_hg19.zip) and choose 7-Zip > Extract files…. Extract them into the data subfolder inside your Exomiser folder, e.g.:

exomiser-cli-15.0.0/data

Step 5: Configure application.properties

Open the file exomiser-cli-|version|\application.properties in a text editor (e.g. Notepad). Find the data version lines and make sure they match the version you downloaded (e.g. 2512):

exomiser.hg19.data-version=2512
exomiser.phenotype.data-version=2512

If you downloaded hg38 instead of (or as well as) hg19, also add or update:

exomiser.hg38.data-version=2512

Save the file.

Step 6: Open a Command Prompt and run a test analysis

Open Command Prompt, navigate into the Exomiser folder, and run the test analysis:

cd exomiser-cli-15.0.0
java -jar exomiser-cli-15.0.0.jar analyse --analysis examples/test-analysis-exome.yml

If Exomiser runs and produces output, your installation is working correctly.

Linux/macOS Installation

Copy and run the following commands in your terminal. The data download is approximately 80 GB and may take several hours depending on your internet speed.

# Download the Exomiser program (small, fast)
wget https://github.com/exomiser/Exomiser/releases/download/exomiser-cli-15.0.0-distribution.zip

# Download the data files (large — allow several hours)
# If you only need one genome assembly, download only the relevant file.
wget https://g-879a9f.f5dc97.75bc.dn.glob.us/data/2512_phenotype.zip
wget https://g-879a9f.f5dc97.75bc.dn.glob.us/data/2512_hg38.zip
wget https://g-879a9f.f5dc97.75bc.dn.glob.us/data/2512_hg19.zip

# Extract the program
unzip exomiser-cli-15.0.0-distribution.zip

# Extract the data files into the data subdirectory
unzip 2512_*.zip -d exomiser-cli-15.0.0/data

# Navigate into the Exomiser folder
cd exomiser-cli-15.0.0

Configure application.properties

Open application.properties in a text editor (e.g. nano application.properties) and confirm the data version lines match what you downloaded:

exomiser.hg19.data-version=2512
exomiser.phenotype.data-version=2512

Add or update the hg38 line if you downloaded that assembly:

exomiser.hg38.data-version=2512

Save and close the file.

Run a test analysis

java -jar exomiser-cli-15.0.0.jar analyse --analysis examples/test-analysis-exome.yml

If Exomiser produces output, your installation is working. The test analysis uses a sample containing a known disease-causing variant in the FGFR2 gene.

Linux/macOS Installation via Homebrew

If you have Homebrew installed (https://brew.sh), you can install Exomiser with a single command:

brew install exomiser/tap/exomiser

This will install the Exomiser program. You will still need to download the data files separately (see the Linux/macOS Installation instructions above for the list of files to download from https://github.com/exomiser/Exomiser/releases/latest).

When installed via Homebrew, the first time it is run Exomiser will automatically create the following folders in your home directory:

$ tree ~/.exomiser
/home/user/.exomiser
├── application.properties
└── data

If they are not present run exomiser –version and this should create them. By default, Exomiser will expect the data to be in the ~.exomiser/data directory but this can be changed in the ~.exomiser/application.properties file to suit your needs (see Configuring the Data Directory). For the most part, when using Exomiser installed via Homebrew, once configured, you can replace the java -jar exomiser-cli-|version|.jar incantation used in this manual with just exomiser and it should just work, however you will need to specify explicitly where to write the results as they will default to being written to the current working directory you are calling the exomiser command from (see outputDirectory:)

Configuring the Data Directory

By default, Exomiser expects its data files to be in a data subfolder inside the Exomiser program folder. If you store your data elsewhere, you must tell Exomiser where to find it.

Edit the application.properties file and set the exomiser.data-directory to the full path of your data folder. For example:

exomiser.data-directory=/data/exomiser-data

Your data directory should look something like this (using tree -L 1 /data/exomiser-data/):

/data/exomiser-data/
├── 2512_hg19
├── 2512_hg38
└── 2512_phenotype

A minimal application.properties for hg19 exome analysis:

exomiser.data-directory=/data/exomiser-data
exomiser.hg19.data-version=2512
exomiser.phenotype.data-version=2512

For hg38 only:

exomiser.data-directory=/data/exomiser-data
exomiser.hg38.data-version=2512
exomiser.phenotype.data-version=2512

For both assemblies:

exomiser.data-directory=/data/exomiser-data
exomiser.hg19.data-version=2512
exomiser.hg38.data-version=2512
exomiser.phenotype.data-version=2512

Note

Each genome assembly loaded requires approximately 1.5 GB of RAM. Loading an assembly not present in your data directory will cause Exomiser to fail.

Optional: Overriding Settings from the Command Line

You can override any application.properties setting directly on the command line using -D flags. This is useful if you want to test different configurations without editing the file. For example:

java -Dexomiser.data-directory=/full/path/to/exomiser-data   -Dexomiser.hg19.data-version=|genome_data_version|   -Dexomiser.phenotype.data-version=|phenotype_data_version|   -jar exomiser-cli-15.0.0.jar analyse --sample examples/pfeiffer-phenopacket.yml

Command-line settings take priority over application.properties.

If you installed Exomiser via Homebrew, you will need to do this using environment variables, either with the JAVA_TOOL_OPTIONS environment variable e.g.

export JAVA_TOOL_OPTIONS="-Dexomiser.data-directory=/full/path/to/exomiser-data -Dexomiser.hg38.data-version=2512"

Alternatively, Exomiser will recognise exomiser-specific environment variables, as named in the application.properties file e.g.

export EXOMISER_DATA_DIRECTORY=/full/path/to/exomiser-data
export EXOMISER_HG38_DATA_VERSION=2602

These can be reverted using the unset command e.g. unset EXOMISER_HG38_DATA_VERSION will remove that variable from the environment and exomiser will not try to load that version. Note that Exomiser will still use the version from the application.properties file if it is set there.

Optional: Genomiser / REMM Data

Note

This section is only needed if you intend to use the Genomiser for non-coding variant analysis. Skip this section for standard exome analysis.

Download the REMM data file and tabix index (.tbi) from https://remm.bihealth.org/download

Once downloaded, add the path to the file in application.properties:

exomiser.hg19.remm-path=${exomiser.hg19.data-directory}/ReMM.v0.4.hg19.tsv.gz

If you include REMM as a pathogenicitySources value in your analysis YAML file without completing this step, Exomiser will stop with an error.

Optional: CADD Data

Note

This section is only needed if you want to use CADD pathogenicity scores. Skip this section for standard exome analysis.

Download CADD files from https://cadd.gs.washington.edu/download. Exomiser only requires the score files (not the full annotation files). Download the files for each genome assembly you use. Note that there is also a European mirror site hosted at the Kircher lab in Berlin (https://cadd.bihealth.org/download):

# hg38
wget https://krishna.gs.washington.edu/download/CADD/v1.7/GRCh38/whole_genome_SNVs.tsv.gz
wget https://krishna.gs.washington.edu/download/CADD/v1.7/GRCh38/whole_genome_SNVs.tsv.gz.tbi
wget https://krishna.gs.washington.edu/download/CADD/v1.7/GRCh38/gnomad.genomes.r4.0.indel.tsv.gz
wget https://krishna.gs.washington.edu/download/CADD/v1.7/GRCh38/gnomad.genomes.r4.0.indel.tsv.gz.tbi

# hg19
wget https://krishna.gs.washington.edu/download/CADD/v1.7/GRCh37/whole_genome_SNVs.tsv.gz
wget https://krishna.gs.washington.edu/download/CADD/v1.7/GRCh37/whole_genome_SNVs.tsv.gz.tbi
wget https://krishna.gs.washington.edu/download/CADD/v1.7/GRCh37/gnomad.genomes-exomes.r4.0.indel.tsv.gz
wget https://krishna.gs.washington.edu/download/CADD/v1.7/GRCh37/gnomad.genomes-exomes.r4.0.indel.tsv.gz.tbi

Then update application.properties to enable CADD:

cadd.version=1.4

exomiser.hg19.cadd-snv-path=${exomiser.data-directory}/cadd/${cadd.version}/hg19/whole_genome_SNVs.tsv.gz
exomiser.hg19.cadd-in-del-path=${exomiser.data-directory}/cadd/${cadd.version}/hg19/gnomad.genomes-exomes.r4.0.indel.tsv.gz

# and/or for hg38:
exomiser.hg38.cadd-snv-path=${exomiser.data-directory}/cadd/${cadd.version}/whole_genome_SNVs.tsv.gz
exomiser.hg38.cadd-in-del-path=${exomiser.data-directory}/cadd/${cadd.version}/gnomad.genomes.r4.0.indel.tsv.gz

The .tbi index files must be in the same directory as the .tsv.gz files. To activate CADD in an analysis, include CADD in the pathogenicitySources section of your analysis YAML file:

pathogenicitySources: [POLYPHEN, MUTATION_TASTER, SIFT, CADD]

Warning

If you include CADD or REMM in pathogenicitySources without having downloaded and configured the corresponding data files, Exomiser will not run.

Troubleshooting

Java not found

If you see java: command not found, Java is either not installed or not on your system PATH. Download Java 21+ from https://adoptium.net and follow the installer instructions. After installation, open a new terminal window and try again.

Wrong Java version

Exomiser requires Java 21 or higher. This can be checked by running:

$ java -version

You should see something like this in response:

openjdk 21.0.6 2025-01-21
OpenJDK Runtime Environment (build 21.0.6+7-Ubuntu-124.04.1)
OpenJDK 64-Bit Server VM (build 21.0.6+7-Ubuntu-124.04.1, mixed mode, sharing)

Versions lower than 21 (e.g. 1.5, 1.6, 1.7, 1.8, 9, 10…) will not run exomiser. You can install the latest version from https://adoptium.net or https://jdk.java.net/ for example. On linux your distribution should provide a packaged version. MacOS users might prefer to use a homebrew version via brew install openjdk

If you get the following error message:

Exception in thread "main" java.lang.UnsupportedClassVersionError:
org/monarchinitiative/exomiser/cli/Main : Unsupported major.minor version

or

Error: A JNI error has occurred, please check your installation and try again
Exception in thread "main" java.lang.UnsupportedClassVersionError: org/monarchinitiative/exomiser/cli/Main has been
compiled by a more recent version of the Java Runtime (class file version 55.0), this version of the Java Runtime
only recognizes class file versions up to 52.0

You are running an older unsupported version of Java, update your java installation.

“Permission denied” errors (Linux/macOS)

If you see a permission error when running Exomiser, make sure the .jar file is readable: chmod +r exomiser-cli-|version|.jar

Zip file reported as too big or corrupted (Linux)

If you see an error like:

error: Zip file too big (greater than 4294959102 bytes)

your version of unzip does not support large files. Check with:

unzip -version

Look for ZIP64_SUPPORT in the output. If it is absent, upgrade unzip via your package manager (e.g. sudo apt install unzip). This is not usually an issue on modern Linux distributions.

Out of memory errors

If Exomiser crashes with an out-of-memory error, increase the memory allocation by raising the -Xmx value. For genome analysis, try -Xmx12G or -Xmx16G:

java -Xmx12G -jar exomiser-cli-15.0.0.jar analyse --analysis your-analysis.yml

Exomiser cannot find data files

Double-check that the version numbers in application.properties (e.g. exomiser.hg19.data-version=2512) exactly match the folder names in your data directory (e.g. 2512_hg19). Even a small mismatch will cause Exomiser to fail.

Analysis produces no results

Confirm that the genome assembly specified in your analysis YAML file (hg19 or hg38) matches the data you downloaded and configured. Analysing a VCF called against an assembly you have not loaded will produce an error.