freebayes: haplotype-based variant calling without the alignment ambiguity

The model reads sequences, not alignments

The central idea is stated in one sentence and it is what separates freebayes from most variant callers. It is haplotype-based, in the sense that it calls variants based on the literal sequences of reads aligned to a particular target, not their precise alignment. The documentation says this model is a straightforward generalisation of earlier ones, naming PolyBayes, samtools and GATK, all of which detect or report variants based on alignments, and that this method avoids one of the core problems with alignment-based detection, namely that identical sequences may have multiple possible alignments. That ambiguity is not a corner case. A read that matches the reference in two different places, or that aligns with a gap in more than one position, produces a different local haplotype depending on which alignment you believe, and a caller that commits to the wrong one will call a variant that is not there or miss one that is. Working from the read sequence itself sidesteps the commitment, which is why the method generalises rather than replaces.

Two inputs, and a plain command line

The simplest operation needs only two inputs, a FASTA reference sequence and a BAM-format alignment file sorted by reference position, and the command is short:

freebayes -f ref.fa aln.bam >var.vcf

The output is a variant call file describing the SNPs, indels and haplotype variants between the reference and the alignment, and the CRAM version takes the same shape with a CRAM file instead. Multiple BAM files may be given for joint calling, which is how the tool handles a cohort. The sorting requirement is not a formality, because the caller processes the reference position by position and the tool is written to stream through the alignment rather than hold it in memory, which is a large part of why it copes with a whole genome. The documentation also points at a help flag for the full option list and their defaults, which is worth doing before the first run rather than after, since the defaults are chosen for a particular balance of sensitivity and runtime that may not suit your data.

GVCF output and the coverage skip that changes your results

Two parameters are called out as typically considered, and both are about runtime rather than about the calling model. GVCF output gives you coverage information about sites that were not called, and it is enabled with the gvcf flag, which matters when the next stage of the pipeline needs to know about the negative space rather than just the positive calls. The skip-coverage parameter, with the short form g, skips regions of extremely high coverage in the reference, and the documentation is blunt that these can greatly increase runtime but do not produce meaningful results. The example given excludes regions of 1000 times coverage, and the command combines both flags so the run outputs a GVCF while skipping the high-coverage regions. The phrasing matters. Skipping high-coverage regions is a performance measure and it is stated as not producing meaningful results, which is the same reason a caller that sees 1000 times coverage in a region is usually looking at a repeat or a collapse rather than at a locus.

Ploidy, pooling and the memory cost of high ploidy

The ploidy options are where the tool's flexibility shows and where the traps are. The diploid case is the default, and the pool of examples covers the rest. A different ploidy is set with the p flag, and the pooled sample case assumes a known number of genome copies, which means each sample identified in the BAM file is assumed to have that many copies, with 32 given as the example. The documentation warns that when running with high ploidy settings it may be required to set the use-best-n-alleles option to a low number to limit memory usage, and the example shows a ploidy of 32 with the best-n-alleles limit at 4. That is a real constraint rather than a footnote, since the combinatorial growth in candidate allele combinations is what makes a high ploidy expensive. The pooled-continuous mode is the other branch, described as generating frequency-based calls for all variants passing the input thresholds, which the documentation says is what you would use in the case that you did not know the number of samples in the pool, with the example using a frequency threshold of 0.01 and a minimum support of 1.

Using known variants as priors, and long haplotype calls

Two advanced modes let you bring outside information into the call set. An input VCF, which must be bgzipped and tabix indexed, is given with the at sign flag and forces calls at particular alleles, which is how you ensure a known causal site is in the output regardless of what the reads support. The second mode generates long haplotype calls over known variants, combining the haplotype-basis-alleles flag with a haplotype-length value, and the example uses a length of 50. The distinction is worth keeping straight. The prior VCF forces a call at a given allele, whereas the long haplotype mode uses known variants as the basis on which it assembles longer haplotypes, which is what you want when a read pair spans several sites and you want them phased together. The input VCF has to be bgzipped and tabix indexed, so if you take this path you will need to prepare the file rather than pointing at a plain VCF.

Packaging, dependencies and the vcflib wrinkle

freebayes is provided as a pre-built 64-bit static Linux binary as part of the releases, and the readme says Debian and Conda packages should work too, with badges for the bioconda channel, Homebrew, Guix and Debian testing, plus a Matrix chat badge. The one dependency note at the top of the page is worth knowing before you file a bug, because it says CI tests may fail until vcflib is updated on the main distributions to version 1.0.13, and that this is because of the location of the vcflib include files having moved to the include directory. So a failing test on a recent distribution may be a packaging problem in the environment rather than a fault in the caller. Building from source is a different matter, because the documentation stresses getting the full recursive git checkout and the dependencies, and the repository layout shows why, with submodules, a meson build file and its options, a source directory, a test directory, a python directory, a paper directory with the methods preprint, a doc directory, contrib and examples directories and a guix definition.

Editorial conclusion

freebayes is a good fit for a variant calling pipeline that wants a model where the read sequence is the evidence rather than the alignment, and it remains a reasonable default for many small to mid-sized projects because it needs only a reference and a sorted alignment file. It is the wrong tool for a large cohort where memory and runtime become the binding constraint, and it is the wrong tool if you need allele frequencies computed on a pool without knowing the number of samples, which is what the pooled-continuous mode exists to approximate rather than to solve. It is also the wrong tool if you intend to cite a peer-reviewed methods paper, because the documentation is candid that freebayes was never submitted for review, though it has been used in over a thousand publications. Before running it, read the parameter list rather than relying on defaults, since the skip-coverage and minimum-support options change what gets called. The project is MIT licensed, the last push was on 2026-09-03, and the current release is v1.3.10 from 2025-05-31.

Frequently asked questions

Official sources

1. freebayes/freebayes on GitHub
2. License: MIT
3. Project website
4. README
5. Releases