# vcflib: a C++ core for reading, rewriting and realigning VCF files

> vcflib is a C++ library plus a set of command line tools for working with VCF variant calls, with the Humpty Dumpty pair vcfwave and vcfcreatemulti built to take overlapping and nested alleles apart and put them back together. It suits pipeline builders who want Unix-style streaming and a permissive API rather than a single monolithic caller.

**vcflib/vcflib** —  C++ library and cmdline tools for parsing and manipulating VCF files with python and zig bindings

- Repository: https://github.com/vcflib/vcflib
- Website: https://github.com/vcflib/vcflib#vcflib
- Stars: 687 · Forks: 223
- Language: C++
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/vcflib-vcflib

## A library and a tool collection from the same source

The Variant Call Format is a flat, tab-delimited text format for describing reference-indexed variations between individuals, and it has become the reporting standard for a wide array of genomic variant detectors. vcflib is the layer that sits underneath those detectors.

The project describes itself as two things at once. It is an API for parsing and operating on records of genomic variation as the VCF format describes them, and it is a collection of command-line utilities for executing complex manipulations on VCF files. The extensions and applications shipped inside the library's own utilities in `src/` make up most of its practical utility. The library part is described as a quick and extremely permissive method to read and write VCF files.

That dual shape is the design decision worth noticing. A permissive reader does not reject a record because a field is unusual, which matters when your input comes from several different callers with slightly different habits. The permissive side of that bargain is that the library will not tell you that a record is wrong, and the work of validating VCF falls to you and to the tools you pipe into.

The primary language is C++, the licence is MIT, and the repository also carries infrastructure for Python bindings.

## vcfwave and vcfcreatemulti take nested alleles apart again

The January 2023 release introduced what the project calls its first Humpty Dumpty release. The pair is `vcfwave` and `vcfcreatemulti`, and the document describes them as natural companions.

The problem they attack is that variant callers are not perfect. A VCF file can contain multiple complex, overlapping and even nested alleles. `vcfcreatemulti` can take such a file apart, and `vcfwave` puts it back together, with the stated aim of producing sane VCF output that is useful for analysis and of removing false positives.

The mechanism underneath is the biWFA wavefront aligner, a state-of-the-art wavefront alignment library, which the project included to bring wavefront alignment into the toolchain. The stated purpose is to realign long sequences and reduce the call complexity and false positives that pangenome variant callers introduce.

This is where the tool earns its keep. The documentation is explicit that the pair is particularly useful for the output of structural variation callers and pangenome genotypers, of the kind used by the Human Pangenome Reference Consortium, precisely because those callers produce overlapping ALT segments. If your data is ordinary small-variant VCF output, most of this machinery is irrelevant to you. If it is pangenome output, it is the reason the project exists.

## Four package managers and a static pack, no compile step

vcflib is packaged for the usual bioinformatics channels, which means most users never build it. The documented install paths are Bioconda, Homebrew, Debian and Ubuntu, and GNU Guix.

Conda installs in user land without root access, and Homebrew covers Linux and Mac OS X:

```bash
conda install -c bioconda vcflib
```

```bash
brew install brewsci/bio/vcflib
```

For Debian and Ubuntu the packages are split into tools and development headers:

```bash
apt-get install libvcflib-tools libvcflib-dev
```

The Guix route installs the packaged definition, and the maintainers develop against Guix:

```bash
guix package -i vcflib
```

For environments without a package manager, static binaries, Docker and Singularity images are hosted at files.genenetwork.org, and the Singularity invocation looks like this:

```bash
singularity exec vcflib-version-singularity.pack.gz vcfcreatemulti -h
```

A Debian `libvcflib-dev` package and the CMake build mean the library can also be linked into your own C++ project, which is the route to take when the tools alone are not enough.

## The Makefile is a thin wrapper over cmake

Building from source goes through CMake, and the top-level Makefile exists to make that less painful. It defines `VCF_LIB_LOCAL` as the current directory and derives `BUILD_DIR`, `BIN_DIR`, `LIB_DIR` and `INC_DIR` from it, so a local build does not need a system-wide install prefix. The `all` target creates the build directory if it is missing, runs cmake with `-DCMAKE_INSTALL_PREFIX` pointing at the checkout, then runs make and make install.

The useful part is the set of build flavours, each of which just sets `CMAKE_FLAGS` and delegates:

```bash
openmp:
	CMAKE_FLAGS=-DOPENMP=ON $(MAKE) all

profiling:
	CMAKE_FLAGS=-DPROFILING=ON $(MAKE) all

gprof:
	CMAKE_FLAGS=-DGPROF=ON $(MAKE) all
```

The OpenMP flavour is the one most worth knowing about, because the usage guidance for the utilities is built around streaming with Unix pipes to make use of multi-core systems. Tests are run with `prove` against the files in `tests/`, and `pull` and `update` targets handle fetching upstream changes. The project also ships `vcflib.pc.in` for pkg-config, so linking is a normal library affair.

At the top level you also find a `1KG_Index/` directory, a `contrib/` directory, `examples/` with sample outputs and plots, `man/` and `doc/` directories of per-tool documentation, and a `samples/` directory.

## The visible tool index is small and centred on filtering

The documentation groups the utilities into filter, metrics, phenotype, genotype, transformation, statistics and scripts, and each tool has its own page under `doc/`. The filter group is the part worth reading closely, because it defines what the project considers its core.

`vcfuniq` lists unique genotypes and works like GNU uniq aimed at VCF records. It removes records that have the same position, ref and alt as the previous record on a sorted VCF file, and the documentation is careful about the limit: it does not adjust or combine genotypes in the output, it simply takes the first record. For combining records, the documentation points at `vcfcreatemulti`.

`vcfuniqalleles` works at a finer grain. For each record it removes duplicate alternate alleles that may have resulted from merging separate VCF files, which is the kind of artifact you hit the moment you combine per-sample VCF output. `vcffilter` applies a set of filters to a specified VCF file, with the filters themselves defined in a file.

The wider usage pattern matters as much as the tools. The project encourages driving the utilities in a streaming fashion with Unix pipes, which gives a convenient interface to other libraries that exchange VCF files, and the listed names include vcf-tools, BedTools, GATK, htslib, bio-vcf, bcftools and freebayes. Example pipelines live in `scripts/`.

## Where vcflib is the wrong choice

The clearest limit is scope. vcflib does not call variants. It parses and manipulates calls that some other detector produced, so a team that needs alignment and genotyping should look elsewhere and keep vcflib for the cleanup stage. The tool index visible in the documentation is also narrow, with filtering, deduplication and allele reformatting at its centre, so anyone expecting a full suite of variant analysis commands in one package will find a thinner list than the project title suggests.

The permissive reading style carries a second cost. A library that accepts unusual records will not flag them, and the pipeline tools that do the validation are thinner than the parsing side. If your data quality is unknown, budget time for checking what comes out.

The project itself points at alternatives in a 2022 PLoS Computational Biology paper, described as a spectrum of free software tools for processing the VCF variant call format, and the title names vcflib alongside bio-vcf, cyvcf2, hts-nim and slivar. The difference in approach between vcflib and the rest of that spectrum is the emphasis on a C++ library with a permissive API, a Unix pipeline philosophy, and the wavefront realignment built into the tooling rather than left to a separate step. bcftools and freebayes appear in the documentation as tools you pipe into, which is a different relationship from being one.

On maintenance, the repository is not archived and the last push was on 2026-10-02. The release history is slower than that: v1.0.15 shipped on 2026-03-20, v1.0.14 on 2025-05-18 and v1.0.13 on 2025-04-18. Version 1.0.x with a roughly yearly release train is the pattern, so plan upgrades around a release rather than around a commit.

## Conclusion

Adopt vcflib when your work involves VCF files that other tools leave in a messy state, especially structural variation and pangenome output where ALT segments overlap, and when a Unix pipeline is part of your design. Do not adopt it as a replacement for a variant caller, since it operates on calls that already exist, and do not assume a fresh feature set in the pipeline tools, since the visible tool index is small and centred on filtering. First verify the build against your own compiler, check that the Python bindings match your interpreter, and confirm that the v1.0.15 release notes cover the record layouts your callers emit.

## FAQ

### How do I install vcflib without compiling it?

Use the package manager for your platform: `conda install -c bioconda vcflib`, `brew install brewsci/bio/vcflib`, `apt-get install libvcflib-tools libvcflib-dev` on Debian and Ubuntu, or `guix package -i vcflib`. Static binaries, Docker and Singularity images are also hosted at files.genenetwork.org.

### What are vcfwave and vcfcreatemulti used for in vcflib?

They are the Humpty Dumpty pair. `vcfcreatemulti` takes a VCF file with multiple complex, overlapping and nested alleles apart, and `vcfwave` puts it back together, using the biWFA wavefront aligner to realign long sequences and reduce call complexity. The documentation points them at structural variation and pangenome output with overlapping ALT segments.

### How do I remove duplicate records and duplicate alleles in a VCF file?

`vcfuniq` removes records that share position, ref and alt with the previous record on a sorted VCF file, keeping the first one without combining genotypes. `vcfuniqalleles` removes duplicate alternate alleles inside a record, which is the artifact left by merging separate VCF files.

### Does vcflib have Python bindings?

The project states that infrastructure to write Python bindings has been added, and the bindings are described as part of the library rather than a separate package. The same repository also ships Zig bindings.

### How do I build vcflib from source with OpenMP?

The top-level Makefile wraps cmake. Run `make openmp`, which sets `CMAKE_FLAGS=-DOPENMP=ON` before the normal build, or `make profiling` and `make gprof` for instrumented builds. The build directory, binary, library and include paths are derived from the checkout directory.

## Sources

- [License: MIT](https://github.com/vcflib/vcflib/blob/master/LICENSE)
- [Project website](https://github.com/vcflib/vcflib#vcflib)
- [README](https://github.com/vcflib/vcflib/blob/master/README.md)
- [Releases](https://github.com/vcflib/vcflib/releases)
- [vcflib/vcflib on GitHub](https://github.com/vcflib/vcflib)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vcflib-vcflib