OpenSlide reads whole slide images from a dozen scanner vendors through one C API

The problem it solves

OpenSlide is a C library for reading whole slide image files, also known as virtual slides, and it provides a consistent and simple API for reading files from multiple vendors.

That sentence describes the whole problem. A pathology scanner produces a slide that is far too large to load into memory as a single image, so the file on disk is a pyramid of tiles plus a pile of metadata, and every vendor invented a slightly different way of doing it. Before OpenSlide, opening a slide meant either using the vendor's own SDK, which is Windows-only for some vendors and closed for others, or reverse-engineering the format.

The topic list says it directly: c, pathology, whole-slide-imaging. This is a clinical imaging library, not a general image library, and it is aimed at the digital pathology workflow where a single slide is a gigabyte-scale object and the access pattern is read a region at a time.

The project has been developed by Carnegie Mellon University and other contributors, and has been supported by the National Institutes of Health and the Clinical and Translational Science Institute at the University of Pittsburgh. The DICOM and ICC functionality specifically was supported by NCI Imaging Data Commons. Those funders explain why the format coverage is what it is: this is infrastructure for research, paid for to be interoperable.

The primary language is C, the default branch is main, and the homepage is openslide.org.

The licence is the GNU Lesser General Public License, version 2.1, and the library is distributed in the hope that it will be useful but without any warranty and without even the implied warranty of merchantability or fitness for a particular purpose. For a library that reads files from other people's scanners, that disclaimer is the realistic one.

The vendor formats it covers

OpenSlide can read brightfield whole slide images in several formats, and the list is the most concrete thing the project has to offer.

Aperio, with the .svs extension. ARGOS, with .avs. DICOM, with .dcm. Hamamatsu, with .ndpi, .vms and .vmu. Huron, with .tif. Leica, with .scn. MIRAX, with .mrxs. Philips, with .tiff. Sakura, with .svslide. Trestle, with .tif. Ventana, with .bif and .tif. Zeiss, with .czi. And generic tiled TIFF, with .tif.

Each of those links to a documentation page on the OpenSlide site describing the format, which is the thing to read if you are supporting a particular scanner. That matters because the extension column is misleading on its own. Three vendors use .tif for the generic tiled TIFF path, and they are not the same internal layout, so a file named .tif could be Huron, Trestle, Ventana, Philips or a generic tiled TIFF, and OpenSlide works that out from the file contents rather than the name.

The two extremes of the list are worth noting. Generic tiled TIFF is the open, documented baseline that any tool can produce, and support for it is what makes the library useful as a fallback. MIRAX with .mrxs is at the other end, a vendor format with its own container structure.

The scope statement is also important and easy to miss. The read support is for brightfield whole slide images. Brightfield is the transmission light microscopy that a standard glass slide scanner uses, and fluorescence imaging produces a different kind of file, so a fluorescence scanner's output is outside what this library covers even if it also happens to be tiled TIFF underneath.

Beyond the slide image itself, OpenSlide can also provide access to ICC profiles, textual metadata, and associated images such as a slide label and thumbnail. Those are not cosmetic extras. The slide label is the scanned text of the physical label on the glass, and for a lab with tens of thousands of slides, reading the label is how a slide gets matched to its case.

Building it, and what it depends on

The build system is Meson, and the dependency list tells you what you are signing up for.

To build OpenSlide you will need GCC or Clang, Meson, cairo at 1.2 or later, glib at 2.56 or later, libdicom at 1.3 or later which is automatically built if missing, libjpeg-turbo at 1.3 or later or libjpeg at 9c or later, libpng, libtiff at 4.0 or later, libxml2, OpenJPEG at 2.1 or later, SQLite at 3.14 or later, zlib, and Zstandard.

Then the three commands:

meson setup builddir
meson compile -C builddir
meson install -C builddir

That is a longer dependency list than a typical image library, and each entry has a reason. Cairo is there for compositing the rendered tiles into a viewable image. Glib provides the object system and the platform abstraction. OpenJPEG handles JPEG 2000, which is what several scanner vendors use for their tile payloads. SQLite is used by some of the vendor formats for their own metadata indexes. libtiff handles the TIFF variants. Zstandard is for newer compressed tile payloads. libdicom is for the DICOM path, and the fact that it is automatically built if missing means you do not have to install it yourself, though a system copy will be used if you have one.

The library is C, and the repository root shows the shape of the project: src/ for the implementation, common/ for code shared between the core and the command line tools, tools/ for the utilities such as the slide inspection command, test/ for the test suite, doc/ for the documentation, subprojects/ for the Meson subproject fallbacks, misc/ and scripts/ for auxiliary content, and meson.build with meson_options.txt at the root.

There is also a pyproject.toml, which is a slightly surprising inclusion for a C library. It configures ruff for the Python files in the repository, with a line length of 79 and a py310 target, along with mypy in strict mode and codespell with an ignore list covering checkin, debbugs, subtile and subtiles. Those are the words that appear in the source and in file names, which is a reasonable thing to keep out of a spell check.

The API, the documentation and the tooling

The API reference is available on the web and is also included as doc/html/openslide_8h.html in the source tarball, which is a detail worth knowing if you are working from a downloaded tarball rather than a clone. Additional documentation is available on the OpenSlide website.

The file name openslide_8h.html is Doxygen's naming convention, where the 8 stands for the dot and h for the header. That tells you the public API is a single header, which is the right shape for a C library of this kind: you include one file and you get the whole surface.

The tools/ directory holds the command line utilities, and these are how you inspect a slide without writing any code. The project does not spell out the individual tool names in the visible readme, but a slide inspection utility is the natural thing to reach for first when you are trying to work out why a particular slide will not open, and the CHANGELOG in the repository root is the place to see what has changed between versions.

The test/ directory is where the format support is verified. For a library whose value proposition is reading files produced by other people's hardware, the test suite has to include real sample slides from each vendor, and the presence of a dedicated test directory alongside per-format documentation is the shape you would expect from a project that takes format coverage seriously.

The CHANGELOG.md at the root and the scripts/ directory are the other places worth reading before contributing, together with the .pre-commit-config.yaml, which tells you what the project checks on every commit.

Where OpenSlide fits, and where it stops

The comparison worth making is with the vendor SDKs and with imaging libraries that handle ordinary images.

Against a vendor SDK, the difference is both coverage and licensing. A vendor SDK knows one vendor deeply, including the parts OpenSlide does not implement, but it may be Windows-only, may require a licence from the vendor, and may not exist at all for the smaller scanner makers. OpenSlide gives you one API across a dozen vendors under LGPL-2.1, which is what makes a multi-site lab or a multi-vendor study possible.

Against an ordinary image library, the difference is the access model. A conventional library gives you a whole image, and a whole slide does not fit in memory, so OpenSlide is built around reading regions, with the caller asking for the level and coordinates of a tile. That also means it is not a general image decoder, and pairing it with a conventional library for the small images it produces is normal.

The limits are worth naming. The brightfield scope excludes fluorescence and other non-transmission modalities. The library reads the slide; it does not interpret it, so annotation, cell detection and the rest of the pathology workflow are other projects. And the version history shows long gaps between tags, with v4.0.1 from 2026-06-08, v4.0.0 from 2023-10-11 and v3.4.1 from 2015-04-20, so a project that reaches for OpenSlide will be picking a release from a project that tags occasionally rather than continuously.

The gap between v3.4.1 and v4.0.0 is nearly nine years, and the jump from v4.0.0 to v4.0.1 is under three, which suggests the project is in a stable maintenance phase rather than an active one. That is not a criticism of a library whose API has been stable for a decade, and it is the usual shape for infrastructure that has settled. But it does mean you should read the CHANGELOG for the version you are pinning rather than assuming the newest tag has changed much.

On the licensing side, LGPL-2.1 is the pragmatic choice for a library that has to be linked into closed-source clinical and research software: you can use it commercially, and the requirement attaches to modifications of the library itself rather than to your application. The disclaimer about no warranty is also the honest one for a format compatibility layer, where the upstream vendor can change a format without notice and there is nothing the library can do about it.

The last push was on 2026-10-11 and the repository is not archived.

Editorial conclusion

OpenSlide suits a pathology imaging pipeline or a research tool that has to open slides from several scanner vendors, since the whole point of the library is that the format differences stop being your problem, and the ICC profile and metadata access matters for anything downstream that cares about colour fidelity. It is the wrong tool if you only have a handful of slides from one vendor in a format you already understand, since linking and the dependency list are real costs for that, and it is the wrong tool for fluorescence or other non-brightfield imaging, because the read support is scoped to brightfield whole slide images. Before you build against it, check the format list on the OpenSlide site against the scanners in your own lab, and read the API reference rather than assuming the file extensions are complete, because several vendors use .tif for completely different internal layouts.

Frequently asked questions

Official sources

1. License: LGPL-2.1
2. openslide/openslide on GitHub
3. Project website
4. README
5. Releases