How to Download and Use gnomAD Data
By the end of this guide you will have a local copy of the gnomAD release files you need, a compact allele-frequency index you can query in seconds, and an annotated copy of your own VCF carrying population frequencies, homozygote counts, and gene constraint scores. You need a Unix machine with 1–2 TB of free disk if you plan to keep the full sites VCFs, bcftools and htslib 1.17 or newer, and one of gcloud storage, aws, or azcopy. Add echtvar for annotation and, optionally, Python 3.10 with hail if you want to work on the Hail Tables directly. Everything below assumes you are analyzing your own germline variant calls, and none of it is a substitute for a clinical geneticist reading a report.
1. Pick the release before you pick the file
gnomAD is a series of aggregated callsets. It is not one dataset, and picking the wrong one costs you days. The current main release is v4.1, built on GRCh38, combining 730,947 exomes and 76,215 genomes for 807,162 individuals. The older v2.1.1 release is on GRCh37 with 125,748 exomes and 15,708 genomes, and it remains useful only if your pipeline is stuck on GRCh37 or you need the original v2 constraint scores.
Within v4.1 you have three sites files to choose from: exomes, genomes, and the joint release. The exomes callset gives you the largest sample size and therefore the tightest allele frequency estimates for coding variants. The genomes callset is the only one with usable data in introns, promoters, and intergenic space. The joint release combines the two with harmonized frequencies and is the right default if you are annotating a whole genome and want a single number per variant.
Two things to know about the v4 exomes. Roughly 416,000 of them come from the UK Biobank, so a non_ukb subset is published for anyone whose analysis overlaps that cohort. And the exome capture means allele number (AN) drops sharply outside targeted regions, which we return to in step 5.
If you want individual-level genotypes rather than aggregate frequencies, the aggregate release will not give them to you. The harmonized HGDP and 1000 Genomes callset released alongside gnomAD does, covering several thousand deeply sequenced genomes from a wide set of global populations with a permissive data use policy.1 That resource is the one to reach for when you need per-sample data for principal component analysis or ancestry projection.
2. List the bucket and read the manifest
gnomAD is mirrored on Google Cloud Public Datasets, the AWS Registry of Open Data, and Azure Open Datasets. All three are free to read and none require credentials. Pick the one closest to your compute.
# Google Cloud
gcloud storage ls gs://gcp-public-data--gnomad/release/4.1/vcf/exomes/
# AWS, anonymous
aws s3 ls --no-sign-request \
s3://gnomad-public-us-east-1/release/4.1/vcf/exomes/
Always list before you download. Path layouts change between releases, and the file names encode the release version. In v4.1 the per-chromosome sites files are named like gnomad.exomes.v4.1.sites.chr1.vcf.bgz with a matching .vcf.bgz.tbi index. Genomes and joint files follow the same pattern under vcf/genomes/ and vcf/joint/.
Check the total size before committing disk:
aws s3 ls --no-sign-request --recursive --summarize \
s3://gnomad-public-us-east-1/release/4.1/vcf/exomes/ | tail -3
Every object is also reachable over plain HTTPS, which matters for the next step:
https://storage.googleapis.com/gcp-public-data--gnomad/release/4.1/vcf/exomes/gnomad.exomes.v4.1.sites.chr17.vcf.bgz
https://gnomad-public-us-east-1.s3.amazonaws.com/release/4.1/vcf/exomes/gnomad.exomes.v4.1.sites.chr17.vcf.bgz
3. Do not download the whole thing if you only need a region
The single most useful trick with gnomAD is that tabix reads a bgzip-compressed VCF over HTTPS by range request. You pull the index and a few kilobytes of the body instead of hundreds of gigabytes.
export GNOMAD=https://storage.googleapis.com/gcp-public-data--gnomad/release/4.1/vcf/exomes
tabix -h $GNOMAD/gnomad.exomes.v4.1.sites.chr17.vcf.bgz \
chr17:43044295-43170245 \
| bgzip > brca1.gnomad41.vcf.gz
tabix -p vcf brca1.gnomad41.vcf.gz
bcftools works the same way with -r, and it handles multiple regions from a BED file:
bcftools view -R panel.bed -f PASS -Oz -o panel.gnomad.vcf.gz \
$GNOMAD/gnomad.exomes.v4.1.sites.chr17.vcf.bgz
A caution on region queries: -R uses the index and jumps, while -T streams and filters. For a remote file you want -R. Note also that contigs in v4 carry the chr prefix while v2.1.1 on GRCh37 does not. A query for 17:43044295 against a v4 file returns nothing and no error.
Download the full per-chromosome files only when you are building an annotation index, which is step 5.
4. Learn the INFO fields you will use
The sites VCF has hundreds of INFO fields. In practice you will use a dozen. AC, AN, and AF are the allele count, total called alleles, and frequency across the whole callset. nhomalt is the number of homozygous alternate individuals, which is often more informative than frequency for recessive reasoning.
Suffixes split those counts by genetic ancestry group. The AF_grpmax field is the highest frequency in any single group, and faf95_max is the lower bound of the 95% confidence interval on that group-maximum frequency. The group suffixes give the following fields.
AF_afrAF_amrAF_asjAF_easAF_finAF_midAF_nfeAF_sasAF_amiAF_remaining
For asking whether a variant is too common to be a rare-disease candidate, the filtering allele frequency is the field to use, because it accounts for sampling noise in small groups.
Group-specific frequencies matter more than people expect. Carrier frequencies for autosomal recessive conditions vary by an order of magnitude between ancestry groups in gnomAD, and a global average hides that variation entirely.2 Aggregate databases also have real blind spots: a survey of primary ciliary dyskinesia genes found substantial ethnic heterogeneity in variant prevalence along with under-representation of several populations.3
Two fields control quality. The FILTER column carries PASS or a list of failure reasons, and AS_FilterStatus gives the allele-specific version for multiallelic sites. Filter on PASS unless you have a specific reason not to.
Functional consequence lives in a single packed vep INFO field. Split it into columns with the split-vep plugin:
bcftools +split-vep panel.gnomad.vcf.gz \
-f '%CHROM\t%POS\t%REF\t%ALT\t%AF\t%AF_grpmax\t%nhomalt\t%Consequence\t%SYMBOL\n' \
-d -A tab > panel.tsv
-d expands one row per transcript consequence. Add -s worst if you want a single line per variant instead.
5. Build a local annotation index with echtvar
If you want to annotate your own variants genome-wide, do not run bcftools annotate against raw gnomAD VCFs. The command works, but it is slow and reads far more data than it needs. Encode the fields you care about into an echtvar archive once, then annotate in a few minutes per sample.
Write a config naming the fields and their aliases:
[
{"field": "AF", "alias": "gnomad41_AF", "missing_value": -1,
"multiplier": 2000000},
{"field": "AC", "alias": "gnomad41_AC", "missing_value": -1},
{"field": "AN", "alias": "gnomad41_AN", "missing_value": -1},
{"field": "nhomalt", "alias": "gnomad41_nhomalt","missing_value": -1},
{"field": "AF_grpmax", "alias": "gnomad41_AF_grpmax", "missing_value": -1,
"multiplier": 2000000},
{"field": "faf95_max", "alias": "gnomad41_faf95", "missing_value": -1,
"multiplier": 2000000}
]
The multiplier turns a float into an integer for compression, so a multiplier of 2,000,000 keeps resolution down to 5e-7. Then encode:
echtvar encode gnomad41_exomes.zip conf.json \
gnomad.exomes.v4.1.sites.chr*.vcf.bgz
This is the step that needs the full download. Expect the encode to run for a few hours and the resulting archive to be a small fraction of the input size. Annotation afterwards is fast:
echtvar anno -e gnomad41_exomes.zip mysample.norm.vcf.gz mysample.anno.bcf
Normalize your input first or the join will silently miss variants:
bcftools norm -m -any -f GRCh38.fa -Ou mysample.vcf.gz \
| bcftools norm -d exact -Oz -o mysample.norm.vcf.gz
The alternative is slivar with a gnotate zip, which packages similar logic and adds an expression language for filtering trios. We prefer echtvar when the job is purely annotation, because the config is explicit about which fields you carry forward.
One interpretation rule to build into your filters: a variant absent from gnomAD is not necessarily rare. Check gnomad41_AN at the site. In exome data the allele number collapses at the edges of capture targets, and a site with AN under about 20% of the maximum (roughly 1.46 million alleles for v4.1 exomes) carries almost no information about frequency. Treat those as unobserved rather than absent.
6. Pull the auxiliary tables
The sites VCFs are only part of the release. Several flat files under release/4.1/ are small enough to download in seconds and answer questions the VCFs cannot.
The constraint metrics table gives per-transcript LOEUF, pLI, missense Z scores, and observed-to-expected ratios:
aws s3 cp --no-sign-request \
s3://gnomad-public-us-east-1/release/4.1/constraint/gnomad.v4.1.constraint_metrics.tsv .
LOEUF, the upper bound of the observed-to-expected loss-of-function confidence interval, is the score to sort by. Lower means more constrained. Read it with the sample size in mind: short genes have wide intervals and look unconstrained no matter their biology. Independent signals help here, since promoter CpG density predicts loss-of-function intolerance and adds information for genes too small to score well on LOEUF alone.4
Coverage summaries tell you whether a position was even callable:
aws s3 ls --no-sign-request s3://gnomad-public-us-east-1/release/4.1/coverage/
These are tabix-indexed per-base tables with mean depth and the fraction of samples above depth thresholds. Query them the same way you query the VCFs.
Mitochondrial variation is a separate callset. gnomAD reports mtDNA variants across 56,434 individuals with heteroplasmy levels, which matters because mitochondrial variant interpretation depends on heteroplasmy fraction rather than a simple genotype.5 Structural variants also ship separately, in their own VCFs with SVTYPE and SVLEN fields and breakpoint-based coordinates.
If your interest is non-coding constraint, the genomes callset supports analyses the exomes cannot. Constraint signals have been detected in intronic branch point sequences and in G-quadruplex-forming regions of untranslated regions using population frequency data of this kind.67
7. Use Hail only when you need the whole matrix
Every release is also published as a Hail Table, for example under release/4.1/ht/exomes/gnomad.exomes.v4.1.sites.ht. Hail is the right tool when you want to compute over all 800 million variants: recomputing constraint, joining against your own cohort, or filtering on fields not exported to the VCF.
import hail as hl
hl.init(default_reference="GRCh38")
ht = hl.read_table(
"gs://gcp-public-data--gnomad/release/4.1/ht/exomes/gnomad.exomes.v4.1.sites.ht"
)
ht = ht.filter(hl.len(ht.filters) == 0)
ht.select(AF=ht.freq[0].AF, nhomalt=ht.freq[0].homozygote_count).show(5)
The freq array is indexed, and you resolve indices through the freq_index_dict in the table’s globals. Running this on a laptop against a remote Hail Table will be slow and will pull a lot of data. Use a Dataproc or EMR cluster in the same region as the bucket, or stick to the VCFs. For anything short of whole-dataset computation, the VCF path in steps 3 through 5 is faster and simpler. Cloud-native query layers built over gnomAD-style data lakes exist as a third option when you want SQL rather than Hail.8
Common problems
Contig naming mismatches are the most frequent silent failure. v4 uses chr1, v2.1.1 uses 1, and a mismatched query returns an empty result with exit code 0. Check with tabix -l file.vcf.bgz | head.
Multiallelic sites break naive joins. gnomAD splits multiallelics in the release, but your caller probably does not. Run bcftools norm -m -any followed by left-alignment against the same reference FASTA used for the release.
Indel representation differs even after normalization if your reference differs. GRCh38 has analysis sets with and without alt contigs and with masked pseudoautosomal regions. Use a reference consistent with your caller and confirm that a handful of known indels match by position and allele.
Lifting v2 GRCh37 frequencies to GRCh38 loses variants and flips strands in some regions. If you need GRCh38 frequencies, use v4.1 rather than a lifted v2.
Reading the whole file when you wanted a slice will run for hours and cost egress on a requester-pays bucket. The public mirrors are free to read, but a Hail job left running on a cluster is not.
Finally, treat a frequency in gnomAD as a measurement with an uncertainty rather than a fact. Use faf95_max instead of AF_grpmax when a threshold decision depends on it, and check AN before concluding a variant is absent. When a result has implications for your health or a family member’s, take it to a clinical geneticist or a genetic counselor. Population databases are inputs to interpretation. They are not conclusions.
Footnotes
-
Zan Koenig, Mary T. Yohannes, Lethukuthula L. Nkambule, et al. A harmonized public resource of deeply sequenced diverse human genomes. Genome Research, 2024. https://doi.org/10.1101/gr.278378.123 ↩
-
Matthew J. Schmitz, Mahmoud Aarabi, Ali Bashar, et al. Carrier frequency of autosomal recessive genetic conditions in diverse populations: Lessons learned from the genome aggregation database. Clinical Genetics, 2022. https://doi.org/10.1111/cge.14148 ↩
-
William B Hannah, Bryce A Seifert, Rebecca Truty, et al. The global prevalence and ethnic heterogeneity of primary ciliary dyskinesia gene variants: a genetic database analysis. The Lancet Respiratory Medicine, 2022. https://doi.org/10.1016/s2213-2600(21)00453-7 ↩
-
Leandros Boukas, Hans T. Bjornsson, Kasper D. Hansen. Promoter CpG Density Predicts Downstream Gene Loss-of-Function Intolerance. The American Journal of Human Genetics, 2020. https://doi.org/10.1016/j.ajhg.2020.07.014 ↩
-
Kristen M. Laricchia, Nicole J. Lake, Nicholas A. Watts, et al. Mitochondrial DNA variation across 56,434 individuals in gnomAD. Genome Research, 2022. https://doi.org/10.1101/gr.276013.121 ↩
-
Naveen Kumar Kadri, Xena Marie Mapel, Hubert Pausch. The intronic branch point sequence is under strong evolutionary constraint in the bovine and human genome. Communications Biology, 2021. https://doi.org/10.1038/s42003-021-02725-7 ↩
-
David S. M. Lee, Louis R. Ghanem, Yoseph Barash. Integrative analysis reveals RNA G-quadruplexes in UTRs are selectively constrained and enriched for functional associations. Nature Communications, 2020. https://doi.org/10.1038/s41467-020-14404-y ↩
-
Noam Hadar, Grisha Weintraub, Ehud Gudes, et al. GeniePool: genomic database with corresponding annotated samples based on a cloud data lake architecture. Database, 2023. https://doi.org/10.1093/database/baad043 ↩
Pothos builds longitudinal molecular profiles of individuals: whole-genome sequencing, single-cell RNA sequencing, and plasma proteomics, delivered as a detailed report, every data file, and stored cells. Build your profile.