bcftools is the working surface for VCF and BCF variant files

The vcf commands moved out of htslib, and the calling code out of samtools

The repository states its own history in one sentence, and that sentence explains the shape of the codebase. This is the official development repository for BCFtools, and it contains all the vcf* commands which previously lived in the htslib repository, with vcfcheck, vcfmerge and vcfisec given as examples, along with the samtools BCF calling from the bcftools subdirectory of samtools.

So the project is a consolidation. The variant file commands that used to be spread across htslib are here, and the calling code that used to live inside samtools is here too. The top-level layout reflects the result, with a C file and header for each area of functionality. There are vcfindex.o, tabix.o, vcfstats.o, vcfisec.o, vcfmerge.o, vcfquery.o, vcffilter.o, vcfnorm.o, vcfview.o, vcfannotate.o, vcfroh.o, vcfconcat.o, vcfcall.o, mcall.o, gvcf.o, reheader.o, convert.o, vcfconvert.o, tsv2vcf.o, vcfcnv.o and vcfhead.o, alongside the supporting libraries such as csq.o for consequence, gff.o, HMM.o, consensus.o, ploidy.o, bin.o, hclust.o, cols.o and extsort.o.

The result is a substantial single-purpose C program rather than a general sequencing library. htslib, samtools and tabix remain separate projects, and the file format specifications live on their own HTS-spec page.

For a pipeline author, the practical question is which of these tools you actually call. If your work is variant files, bcftools is the surface. If it is alignments, samtools is. If it is indexing and tabulation, tabix and htslib are. Most real pipelines use two or three of them together, and the file format is what they share.

Everything is one program with many subcommands

The build output list makes the architecture visible: there is a main.o and then one object file per command. That is the bcftools shape, a single executable with a subcommand per operation, and it explains a lot about how a pipeline uses it.

The operations cover the standard surface of variant file work. Merging, in vcfmerge, and intersection, in vcfisec. Querying and filtering, in vcfquery and vcffilter, with a filter.o and cols.o holding the expression and column machinery. Normalisation, in vcfnorm, which is the command that splits multi-allelic records and left-aligns indels. Annotation, in vcfannotate, and consequence handling, in csq.o. Statistics, in vcfstats. Indexing, in vcfindex and tabix.o. Reheader, in reheader.o, for editing the metadata block. And conversion, in convert.o, vcfconvert.o and tsv2vcf.o, which covers moving between representations.

The variant calling side is present too. vcfcall.o and mcall.o hold the multi-sample caller, gvcf.o the gVCF handling, consensus.o the consensus caller, HMM.o the hidden Markov model machinery and hclust.o the haplotype clustering. The ploidy.o and bin.o files suggest genotype likelihood and binning support, and edlib.o is the edit-distance library used for haplotype comparison.

So a single binary can filter, intersect, merge, normalise, annotate and call. That consolidation is convenient when the same file is passed through several of those steps, and it is the reason the project is worth building rather than assembling a handful of smaller tools.

Building it, and what the Makefile expects

This is a C project built from source, and the Makefile in the repository shows the toolchain assumptions directly.

The compiler defaults are plain:

CC       = gcc
AR       = ar
RANLIB   = ranlib
CPPFLAGS =
CFLAGS   = -g -Wall -O2
LDFLAGS  =
LIBS     =

There is also a config.mk.in file at the top level and a configure.ac, so the build supports a configure step, and there is an install-sh script alongside an INSTALL file for the cases where a package manager is not in play. The build is the standard GNU autotools-plus-make arrangement that most academic C projects use, and the INSTALL file in the repository root is the document to read for the exact sequence.

Two settings in the Makefile deserve attention because they change what the binary can do. Plugins are enabled by default:

DYNAMIC_FLAGS = -rdynamic
PLUGINS_ENABLED = yes
PLUGIN_EXT = .so

The shared object extension tells you this is a Linux-shaped default, since the plugin mechanism loads .so files. On another platform the extension and the linking flags have to be adjusted, which is the kind of detail that turns a five-minute build into an afternoon on a machine that is not the one the maintainer uses.

The -rdynamic linking flag is what makes a plugin able to call back into the main program, so a plugin can use the library functions the host binary already resolved.

The project also carries two CI configurations, an appveyor one and a Cirrus CI one wired to the develop branch, and the README points to the installation instructions hosted on the samtools.github.io site for the wider set of options including Bioconda and package manager builds.

Version numbers and the develop branch

The release history is short and slightly confusing, and it is worth reading carefully before you pin a version.

The recent releases listed are 1.24 on 2026-07-09, 1.23.2 on 2026-07-10 and 1.22.2 on 2026-07-10. Two patch releases dated after the 1.24 release is the pattern here, and it reflects the project's convention of branching a maintenance line for a released version and then continuing on the next.

The default branch is develop, not main, and the build status badge in the README points at the develop branch of the Cirrus CI configuration. That is the branch where the work happens, and it is where a user who wants the newest behaviour should be looking. It also means a plain clone gives you development state rather than a release.

The last push was on 2026-10-19, so the branch is being worked on. The repository is not archived.

For an adopter, the practical approach is to decide whether you want a release or the branch. A release gives you a fixed point and the branch gives you fixes and new behaviour. What you should not do is assume a release tarball and the branch are interchangeable, because the branch can move underneath a pipeline that expects a stable set of outputs.

The NEWS file at the top level is the changelog, and it is the file to read when a bcftools invocation behaves differently than it did last year.

What the tool does not do for you

The limits here are the limits of the format and of the design, and they are worth being blunt about.

The first is that these are programs, not a library. There is no Python or R API in this repository. A pipeline that wants to manipulate variant data in memory calls the binary and parses its output, which is fine for a shell pipeline and a nuisance for anything that wants to work with the data as objects. A team with an existing analysis framework will usually find itself shelling out and re-parsing, and that is the point at which a different kind of tool is the better answer.

The second is that bcftools works on variant files, and a variant file is a lossy description of a genome. It holds calls and the evidence attached to them, not the reads. A task about coverage, about mapping quality, or about the alignment itself belongs to samtools, and bcftools cannot recover it.

The third is the plugin system, which is a double-edged feature. It lets a site add a filter or an annotator without patching the main program, which is genuinely valuable in a lab with local conventions. It also means the behaviour of a bcftools installation depends on which .so files are present, and a plugin that loads a different library version than the host binary can fail in ways that are hard to read.

The fourth is the build. There is no binary distribution promised in the README beyond the install instructions, and the default Makefile settings assume gcc and a Unix-like plugin extension. A locked-down environment without a compiler needs a container or a package manager route rather than a source build.

None of this makes the toolkit a poor choice. It makes it a choice about wanting the standard command line tools for variant files rather than a programmable interface.

Licence text, and the paper the project asks you to cite

The licence field on the repository carries a custom classification that GitHub cannot map to a standard identifier, so the terms are in the LICENSE file at the root and that file is the one to read.

The build files give a strong hint about what is in it. The Makefile header carries the MIT-style permission notice, the kind that grants use, copying, modification, merging, publication, distribution, sublicensing and selling, on the condition that the copyright notice and the permission notice are included in all copies or substantial portions of the software. There is an AUTHORS file at the top level for the copyright holders, and the source headers in the repository are consistent with that notice.

So the expectation is a permissive licence, but the field says custom, and for a tool that ends up in commercial pipelines it is worth reading the LICENSE file rather than assuming. Nothing here is legal advice.

The citation request is part of the same contract. The project asks users to cite a paper when using BCFtools in publications, and it points at the publications page. The paper is the GigaScience article Twelve years of SAMtools and BCFtools, by Danecek, Bonfield, Liddle, Marshall, Ohan, Pollard, Whitwham, Keane, McCarthy, Davies and Li, in volume 10, issue 2 of February 2021, with the DOI given in the BibTeX entry. The abstract quoted in the README states that both SAMtools and BCFtools are freely available on GitHub under the permissive MIT licence, free for both non-commercial and commercial use, and that both have been installed more than a million times via Bioconda.

The support arrangement is also spelled out. Bugs and feature requests go to the GitHub issue tracker for BCFtools, while any security related issue should be sent by mail to [email protected] instead of being reported in the tracker. The project is hosted by Genome Research Ltd, and the author line in the Makefile is Petr Danecek.

Editorial conclusion

bcftools suits a genomics pipeline that treats VCF and BCF files as its working format and needs the standard set of operations, merging, filtering, querying, annotating, normalisation and calling, in one place with one file format model. It is the wrong tool for a team that wants a Python API rather than a set of command line programs, and the wrong tool for anyone who cannot build C against htslib. Before you adopt it, read the INSTALL file in the repository, build from the develop branch rather than assuming a release tarball matches it, and check the licence text yourself, because the licence field carries a custom classification while the source headers carry an MIT-style notice.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. samtools/bcftools on GitHub