# HTSlib: the C library underneath samtools and bcftools

> HTSlib is a unified C library for reading and writing the file formats that high-throughput sequencing produces, and it is the layer that samtools and bcftools are built on. Its dependency list is one library long, and the formats it handles have become international standards, which is why a bug in it is everybody's problem.

**samtools/htslib** — C library for high-throughput sequencing data formats

- Repository: https://github.com/samtools/htslib
- Stars: 956 · Forks: 480
- Language: C
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/samtools-htslib

## One library for the formats everyone uses

The description in the readme is short and the position is clear.

HTSlib is an implementation of a unified C library for accessing common file formats, such as SAM, CRAM and VCF, used for high-throughput sequencing data, and it is the core library used by samtools and bcftools.

Three things follow from that position. First, the scope is formats, not algorithms. There is no variant calling in here, no alignment, no statistics. There is a way to open a file, walk its records, and write it out again, and it handles the compression, the indexing and the container formats that make those files practical to store.

Second, the dependency list is a single item. HTSlib only depends on zlib. Everything else, the compression, the indexing, the random access, the remote file access, is in the tree.

Third, it is a C library, and it is known to be compatible with gcc, g++ and clang. A library that other people's command line tools, pipelines and language bindings all sit on has to compile cleanly with several toolchains, and the fact that this is stated rather than assumed tells you it is tested that way.

The formats themselves are the substance. The paper the project asks you to cite puts it plainly, that since the original publication of the variant call format and the sequence alignment format, an explosion of software tools have been created to process these data files, and the file formats have become international standards under the jurisdiction of a global genomics alliance.

## The index, and the tools that come with it

One implementation detail is worth explaining, because it explains why the library reads files faster than it otherwise would.

HTSlib implements a generalized BAM index, with the file extension for the coordinate-sorted index. The file reader first looks for the new index and then for the old one if the new one is absent.

That fallback is the kind of detail that only matters in production. A library that could only read the new index would fail on every file produced by an older tool, and a library that insisted on the old one would fail on every file produced by a newer one. Supporting both, and preferring the newer, is what lets a pipeline span versions without a migration step.

The project also includes two tools that have escaped the library and become standard in their own right. The first is the tabix indexer, which creates both the traditional index format and the generalised one. The second is the bgzip compression utility, which writes the block compressed gzip variant that makes indexed random access possible inside a gzip container, and which is now used well outside sequencing.

So a library that describes itself as a format accessor is also the home of two of the most widely used tools in genomics. That is not an accident of packaging, it is a consequence of the formats being designed for indexed random access and the library being the place where that access is implemented.

## Building from the repository is not the same as building the tarball

The build section is short, and it contains a warning that will save a confusing afternoon.

Release tarballs contain generated files that have not been committed to the repository, so building the code from a git checkout requires extra steps.

```sh
autoreconf -i  # Build the configure script and install files it uses
./configure    # Optional but recommended, for choosing extra functionality
make
make install
```

The first step regenerates the configure script and the install machinery, which are produced by the autotools and therefore not in version control. The second is the configuration step, and the comment marks it as optional but recommended, for choosing extra functionality, which is how the optional codecs, the remote access backends and the other build-time switches are turned on.

That is the normal arrangement for a C library with an autotools build, and the advice for most users is to take the release tarball, where the generated files are already there and the build is the last two commands.

The tarballs are published on the project's own download site rather than only as repository tags, which is the older and more convenient convention for a C library whose users include people who do not have the autotools installed.

## What the paper says, and the performance history

The citation section asks you to use a specific paper, and the abstract quoted in the readme is unusually informative about how the project has been used.

The paper is from GigaScience in 2021, authored by the people who maintain the library. The abstract explains that a library was produced out of the original samtools implementation with a focus on performance and robustness, and that the formats have become international standards.

The performance claims are specific and dated, which is the way to state them. Since the original samtools release, performance has been considerably improved, with a BAM read and write loop running five times faster and BAM to SAM conversion thirteen times faster, both using sixteen threads and compared against a particular early samtools version.

Then the reach, which is the part that matters for an evaluator. Widespread adoption has seen the library downloaded more than a million times from GitHub and from the conda channel. The C library has been used directly by an estimated nine hundred projects on GitHub, and it has been incorporated into Perl, Python, Rust and R, which significantly expands the number of uses through those languages.

The abstract also names what changed since the original code, and that list is a decent summary of a decade of work: newer access protocols, the addition of the CRAM file format, better indexing and iterators, and better use of threading.

The licence named in the abstract is the MIT and BSD option, and the repository listing records a custom licence that the platform cannot classify, with a licence file at the root, so the file is the authority.

## The source tree is a map of the formats

The top level of the repository is a long list of C files, and it reads as a table of contents for the library.

The central file handles the file abstraction, and there is a second one for the file format dispatch and the option parsing. The header handling has its own pair of files, the sequence index has its own, and there are the string handling, the checksum, the multipart upload and the plugin system. The pileup code, which computes read depth over alignments, has its own file, and the variant data has a separate directory of sources for the sorting and filtering operations.

Two directories are worth naming. The compression codecs directory has its own makefile fragment for the bundled codecs and another for the external ones, which is how a library lets you build against system libraries or ship its own. And the samples directory holds a couple of dozen small programs, one per feature, including the ones that modify alignments, read specific regions of an index, work with the sequence index and dump auxiliary fields, which is documentation in executable form.

There are also the manual pages for the file access and the annotation tools, a probe script that checks the compiler, a fuzzing settings header, and a document about large positions, which is the kind of edge case note that only exists in a library with a long history of users who found the edge case.

## Support, security and the release pattern

The support section is two lines and the second one matters more than the first.

Bugs and feature requests go to the GitHub issue tracker. For any security related issue, the readme asks you to send a mail to an address at the Sanger Institute instead of reporting in the issue tracker.

That separation is right, and it is also a statement about the project's institutional context. The library is developed at the Wellcome Sanger Institute, the same organisation that maintains samtools, and the licence in the build file carries a copyright to Genome Research Limited for the period from 2013 to 2026, with the usual permissive notice attached.

The default branch is the development one, which is the convention for a library where the released tarballs are the stable artefacts, and the release history shows three versions published on the same day in July 2026, which is the pattern of a coordinated release of a library and the tools that depend on it.

The last push was on 2026-10-19 and the repository is not archived, so the work is continuous, and the fact that the most recent releases are batched on a single day suggests the project treats a release as a coordinated event across the family of tools rather than as a per-library affair.

## Conclusion

HTSlib suits anyone writing their own tool against sequencing data, since it is the fastest and most complete implementation of these formats and the one everything else links against. It is a poor fit if you want a tool rather than a library, because the command line tools are separate projects, and a poor fit if you need a scripting language binding, because those are the community's problem rather than the library's. Before you depend on it, check the licence, which is a permissive MIT style notice with a separate file, and build from a release tarball rather than the repository if you want the generated files to be consistent.

## FAQ

### What is HTSlib used for?

It is a unified C library for reading and writing the file formats used in high-throughput sequencing data, such as SAM, CRAM and VCF. It is the core library that samtools and bcftools are built on, and it depends only on zlib.

### Why does building HTSlib from the git repository need extra steps?

Because the release tarballs contain generated files that are not committed to the repository, so a git checkout needs the autotools to be run first to build the configure script and the install files it uses. The configuration step is then recommended for choosing the optional functionality.

### What other tools does HTSlib provide besides the library?

The tabix indexer, which creates both the traditional index format and the generalised coordinate-sorted one, and the bgzip compression utility, which writes the block compressed gzip variant that makes indexed random access possible inside a gzip container.

### How should I report a security problem in HTSlib?

By email, to the address given in the readme, rather than through the public issue tracker. Ordinary bugs and feature requests do go to the GitHub issue tracker.

## Sources

- [Issues](https://github.com/samtools/htslib/issues)
- [README](https://github.com/samtools/htslib/blob/develop/README.md)
- [Releases](https://github.com/samtools/htslib/releases)
- [samtools/htslib on GitHub](https://github.com/samtools/htslib)

---

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