vg: a variation graph toolkit for many genomes at once

Nodes, edges and the paths that carry genomes

vg is a set of tools for working with genome variation graphs, and the data structure is the whole idea. A variation graph, as implemented in vg, is composed of nodes labelled by sequences and IDs, edges that connect two nodes via either of their respective ends, and paths that describe genomes, sequence alignments and annotations such as gene models and transcripts as walks through nodes connected by edges. The model is similar to the sequence graphs used in assembly and multiple sequence alignment, which gives vg a lineage in assembly tooling rather than in variant annotation. What it stores is many genomes at once, encoded succinctly, instead of one reference with a list of differences against it. That is a different starting point, and it changes what the downstream tools have to do.

Paths are why the graph survives being changed

The mechanism that makes vg more than a data format is the treatment of paths. They provide coordinate systems relative to the genomes encoded in the graph, which allows stable mappings to be produced even if the structure of the graph changes, and the variation graph model makes this embedding explicit and essential rather than an add on. The tools maintain paths as immutable during transformations of the graph, and they use paths to project graph relative data into reference relative coordinate spaces. The practical consequence is that you can rebuild, prune or reformat a graph and still map results back onto a genome, because the coordinates travel with the path instead of being tied to a position inside the graph. The documentation is also blunt that a path is not decoration: paths describe alignments and annotations as walks, so the same machinery serves mapping, gene models and haplotypes.

Release builds for Linux, and the six week cadence behind them

The easiest way to get vg is to download one of the release builds for Linux, and the project states a six week release cadence, so its builds are never too far out of date. macOS users are pointed at the build from source instructions instead, which is the first thing to check if you are on a Mac. The release archives are linked from the repository releases page, and the man page lives in the project wiki, with Doxygen API documentation published separately. The tool is not a single binary with one job either. The citation list in the README covers the main paper, the giraffe paper, the long read giraffe paper for the hifi, r10 and chaining-sr modes, the call paper for structural variant genotyping with vg call, the GBZ paper, the HPRC paper for vg deconstruct, the snarls paper and the personalized pangenome paper for vg haplotypes and the giraffe haplotype name option. Each subcommand has a paper behind it, and the project asks you to cite the relevant one.

Cloning with submodules and pulling in the dependencies

Building from source is the route if you cannot use a release or want to work on vg itself, and it starts with a recursive clone, because the repository carries submodules:

git clone --recursive https://github.com/vgteam/vg.git
cd vg

The dependencies are heavy. Protobuf and Jansson development libraries are required, and the test suite additionally needs jq, bc, rs, parallel, hexdump and column from bsdmainutils, and npm for testing the documentation examples. On Ubuntu 22.04 or 26.04 the project expects this to be as simple as:

make get-deps

On other distributions, or without root, the equivalent is a long apt-get install list covering the compiler toolchain, protobuf, ncurses, autotools, samtools, bcftools, tabix, cmake, pandoc, boost, meson, kmc and the compression and font libraries, among others. Building the bundled Cairo and pixman, which currently need version 1.3.0 or newer, adds pipx and meson on top. The compiler requirement is GCC 10 or greater with C++20 support, and GCC up to 15.2.0 is supported, and a 64 bit operating system is required.

make, make -j16, and the binary that lands in bin

The build itself is a make invocation, and the documentation is candid that it is slow, taking anywhere from ten minutes to more than an hour depending on your machine and thread count. You can pass a job count to run that many build threads at once:

make -j16

There is also a static build, make static, which assumes you have static versions of all the dependencies installed on your system. When the build finishes, the binary sits inside the repository, and the documented way to run it is:

./bin/vg

If you want the command available from any directory, the repository root can be added to your PATH on Bash with:

echo 'export PATH="${PATH}:'"$(pwd)"'/bin"' >>~/.bashrc

The documentation also handles the case where that does not take effect, since a .bash_profile in your home directory has to source .bashrc for it to run. The Makefile itself is a conventional C++ layout, with source under src/ split into algorithms, config, io, subcommand and unittest directories, objects written to obj/ and the executable produced in bin/.

The container build parses the Makefile for its own dependencies

The Dockerfiles in the repository take an unusual approach to dependency management, and it is worth understanding before you use them. The image is based on ubuntu:26.04, pulled from a Google mirror of Docker Hub to avoid pull rate limits on automated Quay builds. The dependency list is not hard coded twice. The Dockerfile carries a block delimited by marker lines, and the comment explains that everything between the begin and end markers is clipped out except the line that starts with RUN or a comment, with line continuation slashes removed. The Makefile is described as the One True Dependency List, and the Dockerfile parses it to get the correct dependencies. The beginning of that block looks like this:

###DEPS_BEGIN###
RUN apt-get -qq -y update && apt-get -y install --no-upgrade \
    make git build-essential protobuf-compiler libprotoc-dev libjansson-dev libbz2-dev \

So if you add a dependency to the Makefile, the container build follows, and there is a separate Dockerfile.static for a static image. The repository also carries a Brewfile for the macOS dependency set, an ontology/ directory, a scripts/ directory and a vgci/ directory for continuous integration.

Where the graph model is the wrong shape for the job

The honest limits come from what the model is for. vg encodes many genomes, and if your problem involves one reference genome and a modest set of variants, the graph buys you nothing and costs you a large dependency set, a long native build and a learning curve in a coordinate model that differs from the one in every other genomics tool you use. On the build side there is no shortcut for macOS or Windows, and a from source build needs root or an equivalent manual apt-get line, so distribution and reproducibility are your problem to solve. The tests are not trivial either, since running the suite needs jq, bc, rs, parallel, bsdmainutils and npm on top of the compile dependencies. A more mundane caution: the project states that other libraries may be required and asks for build difficulties to be reported, which is an admission that the dependency surface is not fully pinned by the documentation. On licensing, the licence field on the repository reports a custom licence that GitHub cannot classify, so the LICENSE file is the text that governs use.

Editorial conclusion

Adopt vg when your data spans many genomes or long reads and you need a representation that keeps every sequence instead of projecting everything onto one reference, and when you can accept a large native dependency set and a build that runs from ten minutes to over an hour. Do not reach for it when a linear reference and a VCF already cover your question, since the graph model buys you nothing there. Check first that you have GCC 10 or newer with C++20 support, a 64-bit system, and the Protobuf and Jansson development libraries, and confirm the licence in the LICENSE file, since the licence field on the repository reports a custom licence that GitHub cannot classify. The last push was on 2026-10-13 and the newest release is v1.77.0 from 2026-09-09, on a stated six week cadence.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. vgteam/vg on GitHub