Slideflow: a deep learning library for whole-slide pathology images

The problem Slideflow targets: whole-slide images are not JPEGs

A whole-slide image is a pyramid of tiles measured in gigapixels, and a pathology model rarely trains on the full resolution. The usual workflow is to cut the slide into tiles, normalize stain variation between scanners and labs, train on tile embeddings or on bags of tiles, then map predictions back onto the slide for a pathologist to inspect. Each of those steps has its own tooling, and stitching them together is where most of the engineering time goes.

Slideflow is aimed at that stitching problem. The README describes it as a deep learning library for digital pathology offering a user-friendly interface for model development, designed for both medical researchers and AI enthusiasts. The feature list covers slide processing and stain normalization, weakly-supervised and strongly-supervised training, multiple-instance learning, self-supervised learning, GANs, and explainability outputs including heatmaps, mosaic maps, saliency maps, and synthetic histology. The intended user is someone who has slides and a clinical question but does not want to build a tile pipeline from scratch.

Projects, bags and tiles: how the pieces fit together

Slideflow organizes work around Projects. The README states that experiments are organized into Projects and links to a project_setup page, but the supplied material is truncated at that point, so the exact constructor arguments and the on-disk project layout cannot be confirmed here. What is visible is the shape of the data flow: a Project holds slide references, and the training pipelines consume either whole-slide labels (weakly supervised) or per-tile labels (strongly supervised).

On top of that sit the model families. MIL treats a slide as a bag of tile features and learns an aggregation, which is the standard approach when only a slide-level diagnosis is available. SSL is listed separately, which suggests pretraining on unlabeled tiles before fine-tuning. GAN support connects to the synthetic histology and StyleGAN3 material. Explainability is a first-class output rather than an afterthought: heatmaps and saliency maps are produced from trained models and rendered back onto the slide.

Two environment variables select the plumbing underneath. SF_BACKEND chooses PyTorch or Tensorflow, defaulting to PyTorch when both are installed. SF_SLIDE_BACKEND chooses the slide reader. That two-axis design is the most consequential architectural decision in the library, because the two axes have different format coverage and the slide reader choice constrains which files you can open at all.

Installing Slideflow: three routes and the CUDA coupling

The pip route is two commands. First upgrade the build tooling, then install the package with the cuCIM extra alongside cupy:

pip3 install --upgrade setuptools pip wheel pip3 install slideflow[cucim] cupy-cuda11x

The README is explicit that the cupy package name depends on the installed CUDA version and points to the cupy installation guide, and that cupy is not required if you use Libvips. That is a real coupling: the extra and the CUDA wheel have to agree, and the example pins cuda11x.

The Docker route avoids that matching problem. Pre-configured images ship with OpenSlide or Libvips and either backend:

docker pull jamesdolezal/slideflow:latest-tf docker run -it --gpus all jamesdolezal/slideflow:latest-tf

For the PyTorch image the run command adds a shared memory flag: docker run -it --shm-size=2g --gpus all jamesdolezal/slideflow:latest-torch. The --shm-size flag is not decoration; PyTorch data loaders pass tensors through shared memory, and the default container limit is small.

The source route clones the repository, creates the conda environment from slideflow/environment.yml, activates it, and installs the package in editable mode with cupy:

git clone https://github.com/slideflow/slideflow conda env create -f slideflow/environment.yml conda activate slideflow pip install -e slideflow/ cupy-cuda11x

Note the editable install path: slideflow/ with a trailing slash, which differs from the usual pip install -e . from the repository root. Requirements are Python 3.7 or newer, with a caveat that cuCIM requires Python below 3.10, and either PyTorch 1.9 or newer or Tensorflow between 2.5 and 2.11. The Tensorflow window is narrow and closed at the top, so a project already on a newer Tensorflow cannot use that backend.

Choosing a slide backend is a format decision, not a speed decision

By default Slideflow reads whole-slide images with cuCIM. The README describes cuCIM as much faster than other openslide-based frameworks but supporting fewer slide scanner formats. The Libvips backend is the alternative, and the README lists what it adds: *.scn, *.mrxs, *.ndpi, *.vms, and *.vmu files. Libvips 8.9 or newer is an optional dependency.

That is the trade-off in plain terms. If your scanner produces one of those formats, cuCIM will not open it and you need Libvips, which also means you no longer need cupy. If your slides are in a format cuCIM handles, you get the faster path. The switch is one environment variable:

export SF_SLIDE_BACKEND=libvips

and the deep learning backend is switched the same way:

export SF_BACKEND=tensorflow

The documentation does not, in the material supplied, give a per-format table telling you which formats cuCIM covers, only that the list is shorter. That gap matters at adoption time: the first thing to check is whether your scanner's output opens at all, because no amount of training code fixes an unreadable slide.

The licence boundary runs through the model zoo

The core repository is Apache-2.0, which is permissive. The pretrained models are not all in the core. The README describes a Non-Commercial Add-ons section: installing slideflow-gpl and slideflow-noncommercial provides integrated access to six additional pretrained foundation models (UNI, HistoSSL, GigaPath, PLIP, RetCCL, and CTransPath), the MIL architecture CLAM, the uncertainty quantification algorithm BISCUIT, and the StyleGAN3 GAN framework.

pip install slideflow-gpl slideflow-noncommercial

The package names are the warning. A GPL-licensed add-on and a package explicitly named noncommercial mean that a pipeline which imports them inherits constraints the Apache-2.0 core does not carry. For academic research this is often acceptable. For anything intended to ship in a commercial product, the model you want may be the thing that decides whether you can ship at all. This is a description of how the packages are named and described, not legal advice; the terms of each add-on and each model's own licence need to be read directly.

The practical consequence is that Slideflow is not one dependency. It is a permissive core plus an optional set of add-ons with a different licence posture, and the split falls exactly where the most attractive pretrained weights live.

Where Slideflow is the wrong tool

The clearest limitation is environmental. cuCIM requires Python below 3.10, so a team standardized on a newer interpreter has to either use Libvips and give up the faster reader or stay on an older Python. Tensorflow support stops at 2.11. Neither constraint is a bug, but both are hard edges that a general-purpose framework would not impose.

There is also a scope boundary. Slideflow is built around whole-slide images and the pathology pipeline: tiling, stain normalization, slide-level or tile-level labels, and slide-space visualization. If your data is already a folder of small, pre-cropped images with no slide context, the slide reader, the tiling, and the heatmap machinery are overhead you would be carrying for nothing, and a general training library would be a shorter path.

Finally, the supplied README is thin on the operational side. It does not describe memory requirements per slide, throughput, or how training scales across multiple GPUs. The Docker run command for the PyTorch image sets --shm-size=2g, which hints that data loading is memory-sensitive, but no guidance is given on how to size that for a given dataset. Anyone planning a large training run should treat those numbers as unknown until measured on their own hardware.

How Slideflow differs from plain PyTorch or Tensorflow pipelines

The obvious alternative is to build the pipeline directly on PyTorch or Tensorflow with OpenSlide or cuCIM for reading, a normalization library, and a MIL implementation from a research repository. That approach gives complete control and no extra dependency, and it is what many pathology groups do today. The cost is that tiling, stain normalization, bag construction, cross-validation with site preservation, heatmap generation, and slide-space rendering all become your code to write and maintain.

Slideflow's position is that those pieces are the library. Stain normalization is a documented module rather than a helper function, explainability outputs are generated from trained models, and there is a Studio application described as an interactive user interface for model deployment and for interacting with models and whole-slide images. That last piece is the real difference: a hand-rolled training script produces weights, while Slideflow also produces a way to look at what the model did on a specific slide.

The trade is dependency surface and version constraints against pre-built pipeline components. If your team already has a mature tile pipeline and only needs a model, Slideflow duplicates work you have done. If you are starting from slides and a question, the built-in pieces are the reason to use it.

Maintenance, releases and what to check before adopting

The release history in the supplied material shows 3.0.0 in August 2024, 3.0.1 in September 2024, and 3.0.2 in October 2024, with the repository's last push recorded in May 2026. That combination, a burst of 3.0.x patch releases followed by a long gap before the most recent push, is worth reading carefully: it suggests active work continues without a tagged release during that window, but the material does not say what landed. If you depend on a specific fix, check whether it is in 3.0.2 or only on master.

The upgrade cost is concentrated in the pinned dependencies rather than the Slideflow API. Moving to a newer Python means leaving cuCIM behind. Moving to a newer Tensorflow means leaving that backend behind. The cupy wheel has to track your CUDA version. A Docker image sidesteps most of this, at the cost of running training inside a container with a shared memory limit you have to set yourself.

On licensing, the Apache-2.0 core is straightforward for most uses. The add-ons are not, and they are where the pretrained foundation models live. The concrete next step is to list which models your project needs, check whether each is in the core or in slideflow-gpl or slideflow-noncommercial, and read those terms before writing training code around them.

Editorial conclusion

Adopt Slideflow if you have whole-slide images, a CUDA-capable environment, and a research question that fits weakly-supervised or MIL training. Do not adopt it if you need a permissive licence across every pretrained model, or if your slides are in formats cuCIM does not read and you cannot install Libvips. Before committing, verify three things: that cuCIM or Libvips opens your scanner's files, that your CUDA version matches the cupy package you install, and which of the six foundation models you actually need, because those arrive via slideflow-gpl and slideflow-noncommercial rather than the Apache-2.0 core.

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. slideflow/slideflow on GitHub