Skip to content

Running SnpEff

We show some basic examples how to use SnpEff.

Basic example: Installing SnpEff

Obviously the first step to use the program is to install it (for details, take a look at the download page. You have to download the core program and then uncompress the ZIP file. In Windows systems, you can just double click and copy the contents of the ZIP file to wherever you want the program installed. If you have a Unix or a Mac system, the command line would be:

# Download using wget
$ wget

# If you prefer to use 'curl' instead of 'wget', you can type:
#     curl -L >

# Install
$ unzip

Basic example: Annotate using SnpEff

Let's assume you have a VCF file and you want to annotate the variants in that file. An example file is provided in examples/test.chr22.vcf (this data is from the 1000 Genomes project, so the reference genome is the human genome GRCh37).

You can annotate the file by running the following command (as an input, we use a Variant Call Format (VCF) file available in SnpEff's examples directory).

$ java -Xmx8g -jar snpEff.jar GRCh37.75 examples/test.chr22.vcf > test.chr22.ann.vcf

# Here is how the output looks like
$ head examples/test.chr22.ann.vcf
##SnpEffVersion="4.1 (build 2015-01-07), by Pablo Cingolani"
##SnpEffCmd="SnpEff  GRCh37.75 examples/test.chr22.vcf "
##INFO=<ID=ANN,Number=.,Type=String,Description="Functional annotations: 'Allele | Annotation | Annotation_Impact | Gene_Name | Gene_ID | Feature_Type | Feature_ID | Transcript_BioType | Rank | HGVS.c | HGVS.p | cDNA.pos / cDNA.length | CDS.pos / CDS.length | AA.pos / AA.length | Distance | ERRORS / WARNINGS / INFO' ">
##INFO=<ID=LOF,Number=.,Type=String,Description="Predicted loss of function effects for this variant. Format: 'Gene_Name | Gene_ID | Number_of_transcripts_in_gene | Percent_of_transcripts_affected' ">
##INFO=<ID=NMD,Number=.,Type=String,Description="Predicted nonsense mediated decay effects for this variant. Format: 'Gene_Name | Gene_ID | Number_of_transcripts_in_gene | Percent_of_transcripts_affected' ">
22  17071756    .   T   C   .   .   ANN=C|3_prime_UTR_variant|MODIFIER|CCT8L2|ENSG00000198445|transcript|ENST00000359963|protein_coding|1/1|c.*11A>G|||||11|,C|downstream_gene_variant|MODIFIER|FABP5P11|ENSG00000240122|transcript|ENST00000430910|processed_pseudogene||n.*397A>G|||||4223|
22  17072035    .   C   T   .   .   ANN=T|missense_variant|MODERATE|CCT8L2|ENSG00000198445|transcript|ENST00000359963|protein_coding|1/1|c.1406G>A|p.Gly469Glu|1666/2034|1406/1674|469/557||,T|downstream_gene_variant|MODIFIER|FABP5P11|ENSG00000240122|transcript|ENST00000430910|processed_pseudogene||n.*397G>A|||||3944|
22  17072258    .   C   A   .   .   ANN=A|missense_variant|MODERATE|CCT8L2|ENSG00000198445|transcript|ENST00000359963|protein_coding|1/1|c.1183G>T|p.Gly395Cys|1443/2034|1183/1674|395/557||,A|downstream_gene_variant|MODIFIER|FABP5P11|ENSG00000240122|transcript|ENST00000430910|processed_pseudogene||n.*397G>T|||||3721|
22  17072674    .   G   A   .   .   ANN=A|missense_variant|MODERATE|CCT8L2|ENSG00000198445|transcript|ENST00000359963|protein_coding|1/1|c.767C>T|p.Pro256Leu|1027/2034|767/1674|256/557||,A|downstream_gene_variant|MODIFIER|FABP5P11|ENSG00000240122|transcript|ENST00000430910|processed_pseudogene||n.*397C>T|||||3305|

As you can see, SnpEff added functional annotations in the ANN info field (eigth column in the VCF output file).

Details about the 'ANN' field format can be found in the ANN Field section and in VCF annotation about standard 'ANN' field. Note: Older SnpEff version used 'EFF' field (details about the 'EFF' field format can be found in the EFF Field section).

You can also annotate using the "verbose" mode (command line option -v), this makes SnpEff to show a lot of information which can be useful for debugging.

Here output is edited for brevity:

$ java -Xmx8g -jar snpEff.jar -v GRCh37.75 examples/test.chr22.vcf > test.chr22.ann.vcf
00:00:00.000    Reading configuration file 'snpEff.config'. Genome: 'GRCh37.75'
00:00:00.434    done
00:00:00.434    Reading database for genome version 'GRCh37.75' from file '/home/pcingola/snpEff_v4_0/./data/GRCh37.75/snpEffectPredictor.bin' (this might take a while)
00:00:00.434    Database not installed
    Attempting to download and install database 'GRCh37.75'
00:00:00.435    Reading configuration file 'snpEff.config'. Genome: 'GRCh37.75'
00:00:00.653    done
00:00:00.654    Downloading database for 'GRCh37.75'
00:00:00.655    Connecting to
00:00:01.721    Local file name: ''
00:01:31.595    Download finished. Total 177705174 bytes.
00:01:31.597    Extracting file 'data/GRCh37.75/motif.bin' to '/home/pcingola/snpEff_v4_0/./data/GRCh37.75/motif.bin'
00:01:31.597    Creating local directory: '/home/pcingola/snpEff_v4_0/./data/GRCh37.75'
00:01:31.652    Extracting file 'data/GRCh37.75/nextProt.bin'
00:01:31.707    Extracting file 'data/GRCh37.75/pwms.bin'
00:01:31.707    Extracting file 'data/GRCh37.75/regulation_CD4.bin'
00:01:32.038    Extracting file 'data/GRCh37.75/snpEffectPredictor.bin'
00:01:32.881    Unzip: OK
00:01:32.881    Done
00:01:32.881    Database installed.
00:01:58.779    done
00:01:58.813    Reading NextProt database from file '/home/pcingola/snpEff_v4_0/./data/GRCh37.75/nextProt.bin'
00:02:01.448    NextProt database: 523361 markers loaded.
00:02:01.448    Adding transcript info to NextProt markers.
00:02:02.180    NextProt database: 706289 markers added.
00:02:02.181    Loading Motifs and PWMs
00:02:02.181        Loading PWMs from : /home/pcingola/snpEff_v4_0/./data/GRCh37.75/pwms.bin
00:02:02.203        Loading Motifs from file '/home/pcingola/snpEff_v4_0/./data/GRCh37.75/motif.bin'
00:02:02.973        Motif database: 284122 markers loaded.
00:02:02.973    Building interval forest
00:02:41.857    done.
00:02:41.858    Genome stats :
# Genome name                : 'Homo_sapiens'
# Genome version             : 'GRCh37.75'
# Has protein coding info    : true
# Genes                      : 63677
# Protein coding genes       : 23172
# Transcripts                : 215170
# Avg. transcripts per gene  : 3.38
# Checked transcripts        :
#               AA sequences : 104254 ( 114.79% )
#              DNA sequences : 179360 ( 83.36% )
# Protein coding transcripts : 90818
#              Length errors :  14349 ( 15.80% )
#  STOP codons in CDS errors :     39 ( 0.04% )
#         START codon errors :   8721 ( 9.60% )
#        STOP codon warnings :  21788 ( 23.99% )
#              UTR sequences :  87724 ( 40.77% )
#               Total Errors :  21336 ( 23.49% )
# Cds                        : 792087
# Exons                      : 1306656
# Exons with sequence        : 1306656
# Exons without sequence     : 0
# Avg. exons per transcript  : 6.07
# WARNING!                   : Mitochondrion chromosome 'MT' does not have a mitochondrion codon table (codon table = 'Standard'). You should update the config file.
# Number of chromosomes      : 297
# Chromosomes names [sizes]  :
#       'HG1292_PATCH' [250051446]
#       'HG1287_PATCH' [249964560]
#       'HG1473_PATCH' [249272860]
#       'HG1471_PATCH' [249269426]
#       'HSCHR1_1_CTG31' [249267852]
#       'HSCHR1_2_CTG31' [249266025]
#       'HSCHR1_3_CTG31' [249262108]
#       'HG999_2_PATCH' [249259300]
#       'HG989_PATCH' [249257867]
#       'HG999_1_PATCH' [249257505]
#       'HG1472_PATCH' [249251918]
#       '1' [249250621]
#       'HG1293_PATCH' [249140837]
#       'HG686_PATCH' [243297375]
#       'HSCHR2_1_CTG12' [243216362]
#       'HSCHR2_2_CTG12' [243205453]
#       'HSCHR2_1_CTG1' [243205406]
#       'HG953_PATCH' [243199374]
#       '2' [243199373]

00:02:59.416    Predicting variants

WARNINGS: Some warning were detected
Warning type    Number of warnings

00:03:04.327    Creating summary file: snpEff_summary.html
00:03:04.891    Creating genes file: snpEff_genes.txt
00:03:17.334    done.
00:03:17.336    Logging
00:03:18.337    Checking for updates...

Notice how SnpEff automatically downloads and installs the database. Next time SnpEff will use the local version, so the installation step is only done once.

The annotated variants will be in the new file "test.chr22.ann.vcf".


SnpEff creates a file called "snpEff_summary.html" showing basic statistics about the analyzed variants. Take a quick look at it.


We used the java parameter -Xmx8g to increase the memory available to the Java Virtual Machine to 4G. SnpEff's human genome database is large and it has to be loaded into memory. If your computer doesn't have at least 4G of memory, you probably won't be able to run this example.


If you are running SnpEff from a directory different than the one it was installed, you will have to specify where the config file is. This is done using the '-c' command line option:

java -Xmx8g -jar snpEff.jar -c path/to/snpEff/snpEff.config -v GRCh37.75 test.chr22.vcf > test.chr22.ann.vcf

Detailed examples

Take a look at several detailed examples in our examples page.

Specify a configuration file

Sometimes you need to specify the path to the config file. For instance, when you run SnpEff from a different directory than your install directory, you have to specify where the config file is located using the '-c' command line option.

java -Xmx8g path/to/snpEff/snpEff.jar -c path/to/snpEff/snpEff.config GRCh37.75 path/to/snps.vcf


Since version 4.1B, you can use the -configOption command line option to override any value in the config file

Java memory options

By default the amount of memory set by a java process is set too low. If you don't assign more memory to the process, you will most likely have an "OutOfMemory" error.

You should set the amount of memory in your java virtual machine to, at least, 2 Gb. This can be easily done using the Java command line option -Xmx. E.g. In this example I use 4Gb:

# Run using 4 Gb of memory
java -Xmx8g snpEff.jar hg19 path/to/your/files/snps.vcf

Note: There is no space between -Xmx and 4G.

Running SnpEff in the Cloud

You can run SnpEff in a "the Cloud" exactly the same way as running it on your local computer. You should not have any problems at all.

Here is an example of installing it and running it on an Amazon EC2 instance (virtual machine):

$ ssh -i ./aws_amazon/pcingola_aws.pem

       __|  __|_  )
       _|  (     /   Amazon Linux AMI

[ec2-user@ip-10-2-202-163 ~]$ wget
[ec2-user@ip-10-2-202-163 ~]$ unzip
[ec2-user@ip-10-2-202-163 ~]$ cd snpEff/
[ec2-user@ip-10-2-202-163 snpEff]$ java -jar snpEff.jar download -v hg19
00:00:00.000    Downloading database for 'hg19'
00:00:36.340    Done
[ec2-user@ip-10-2-202-163 snpEff]$ java -Xmx8g -jar snpEff.jar dump -v hg19 > /dev/null
00:00:00.000    Reading database for genome 'hg19' (this might take a while)
00:00:20.688    done
00:00:20.688    Building interval forest
00:00:33.110    Done.

As you can see, it's very simple.

Loading the database

One of the first thins SnpEff has to do is to load the database. Usually it takes from a few seconds to a couple of minutes, depending on database size. Complex databases, like human, require more time to load. After the database is loaded, SnpEff can analyze thousands of variants per second.

Command line vs Web interface

In order to run SnpEff you need to be comfortable running command from a command line terminal. If you are not, then it is probably a good idea to ask you systems administrator to install a Galaxy server and use the web interface. You can also use the open Galaxy server, but functionality may be limited and SnpEff versions may not be updated frequently.