What the Header of Your VCF File Tells You

What the header is

A VCF (Variant Call Format) file is plain text in three parts. The specification describes them as meta-information lines that start with ##, a single header line that starts with #CHROM, and then data lines, one per position, with tab-separated fields. Everything above the first data line is the header.

The header is the file documenting itself. It records which version of the format was used, which reference genome the positions refer to, what every abbreviation in the data lines means, and which column holds whose genotypes. Reading it before you upload or analyze anything is the easiest way to avoid the classic mistake: feeding a file built on one genome build into a tool that expects another.

How to view only the header

Genome VCFs are usually compressed (.vcf.gz) and can be large, so don't try to open them in Notepad or a spreadsheet. The options below need a terminal.

With bcftools (macOS, Linux, or Windows via WSL)

bcftools view -h your-file.vcf.gz

The bcftools manual describes -h, --header-only as "output the VCF header only." One wrinkle: bcftools view appends its own version and command-line lines to the header it prints unless you add --no-version. If you want the header almost exactly as stored, use:

bcftools head your-file.vcf.gz

bcftools and samtools are available through Homebrew on macOS and through Bioconda on Linux and WSL.

Without bcftools

Compressed VCFs are normally written with bgzip, which its manual describes as compatible with gzip, so standard tools can read them:

zcat your-file.vcf.gz | grep '^#'
# if zcat complains (some macOS versions), use:
gunzip -c your-file.vcf.gz | grep '^#'

The header prints straight away, but grep keeps reading to the end of the file, which can take a while on a big genome. It's safe to stop it once the #CHROM line has appeared.

On Windows

The smoothest route is Windows Subsystem for Linux. Microsoft's instructions are to run wsl --install in an administrator PowerShell window (Windows 10 version 2004 or later, or Windows 11), restart, and then use the same commands as above. Without WSL, extract the .vcf.gz with an archive tool such as 7-Zip, then show the first lines in PowerShell:

Get-Content .\your-file.vcf -TotalCount 300

Raise the number if the #CHROM line hasn't appeared yet.

##fileformat: the version line

The specification requires exactly one ##fileformat line, and it must be the first line of the file, for example ##fileformat=VCFv4.2. The current version in the hts-specs repository is 4.5, but files labelled 4.1 to 4.3 are still very common. If an older tool refuses a file, this line is the first thing to check.

##reference and ##contig: which genome the positions refer to

##reference usually points to the reference FASTA used during alignment. The specification's own example is ##reference=file:///seq/references/1000GenomesPilot-NCBI36.fasta. It isn't mandatory, and it's often a path on the lab's server that means nothing on your computer, but the file name is a useful clue. Look for strings such as GRCh38, hg38, GRCh37 or hg19.

##contig lines describe each reference sequence (chromosome, mitochondrial sequence, unplaced pieces) that the file may refer to. The specification recommends them for VCF and requires them for BCF. Each must have an ID and may carry a length, an md5 checksum of the sequence, a URL, and extras such as assembly:

##contig=<ID=chr1,length=248956422>

That length is useful, as the build section below explains.

##INFO, ##FORMAT and ##FILTER: the dictionary

These structured lines define every code you'll meet in the data lines. If you see DP=31 or GT:AD:DP:GQ and wonder what it means, the answer is in one of these lines.

Number says how many values to expect: an integer, or a special code. A means one per alternate allele, R one per allele including the reference, G one per possible genotype, and . a variable count. Type is Integer, Float, Flag, Character or String. In the FILTER column itself, PASS means the site passed all filters, and a missing value (.) means no filters were applied.

You may also see ##ALT lines for symbolic alleles, ##SAMPLE or ##PEDIGREE lines, and lines left by the software that made the file, recording program versions and command lines. Those last ones are handy if you ever need to ask your provider how a file was produced.

The #CHROM line and your sample column

The last header line names the columns. The specification fixes the first eight: #CHROM POS ID REF ALT QUAL FILTER INFO. If the file contains genotypes, a FORMAT column follows, then one column per sample, named with a sample ID. Duplicate sample IDs aren't allowed, and the line is tab-delimited.

• One column after FORMAT: a single-sample file, typical of a personal genome.
• Several: a multi-sample file, such as a family or trio.
• Nothing after INFO: a sites-only file with no genotypes at all.

To list the sample names alone, run bcftools query -l your-file.vcf.gz. The sample name is whatever ID the lab assigned. If it's an order number, a kit barcode or your name, remember that before sharing the file; the privacy checklist covers the rest.

How to spot the genome build

Positions in GRCh37 and GRCh38 differ, so a tool or annotation set on the wrong build gives wrong answers without any error message. Check in this order:

1. The ##reference file name, if present.
2. Contig lengths. According to the Genome Reference Consortium, chromosome 1 is 248,956,422 bases long in GRCh38 and 249,250,621 in GRCh37. Find the chr1 (or 1) ##contig line and compare.
3. Assembly tags, such as assembly= on contig lines.

Chromosome naming (chr1 versus 1) is a convention, not proof of a build. UCSC's hg19 is GRCh37 and hg38 is GRCh38, but files from either build can use either style. Small details can still differ between "flavours" of the same build. UCSC notes, for example, that its hg19 mitochondrial sequence is not the revised Cambridge Reference Sequence. If a tool asks for a build, match the one in your header rather than guessing.

Single-sample VCF or gVCF?

A regular VCF lists the positions where a variant was called. A gVCF (genomic VCF), in GATK's description, "has records for all sites, whether there is a variant call there or not", grouping runs of non-variant positions into blocks. Header and first-record clues:

• An ALT allele of <NON_REF> (GATK) or <*> (the newer spec's unspecified allele) on most records
• An END INFO field marking where each reference block ends
• ##GVCFBlock lines defining the quality bands GATK uses for those blocks
• File names ending in .g.vcf.gz, though names alone aren't reliable

gVCFs are larger and mainly meant for joint analysis. Many consumer tools expect a variant-only VCF, so check what a tool accepts before uploading. Our list of free VCF tools is a starting point.

Let the file inspector read it for you

If you'd rather not use a terminal, the genome file inspector reads an uncompressed .vcf in your browser without uploading it. It looks at the first few megabytes and reports the format, a genome build if the header names one, the sample name(s) from the #CHROM line, and the chromosome naming style. For a .vcf.gz it identifies the file by name only, so decompress a copy first if you want the header details.

Common questions

Keep going

Sources

Checked in October 2026 against the VCF 4.5 specification (and the 4.3 text) in samtools/hts-specs, the bcftools and bgzip manuals (htslib 1.24 documentation sources), the Genome Reference Consortium's chromosome length tables, GATK's GVCF article, UCSC's hg19 README and Microsoft's WSL install page. Omitted for lack of verification: typical header lengths, which providers use which sample-naming scheme, and apt package names for Ubuntu.

• VCF v4.5 specification (samtools/hts-specs)
• bcftools manual (view -h, head, query -l)
• Genome Reference Consortium: human assembly data and chromosome lengths
• GATK: GVCF, Genomic Variant Call Format
• UCSC hg19 (GRCh37) download README
• Microsoft: Install WSL

Educational content, not medical advice. A genetic result is information, not a diagnosis; for anything medically important, talk to a qualified clinician or genetic counselor. Some outbound links are affiliate links; see the disclosure.