Table of Contents
Shortcuts

Installation

https://github.com/user-attachments/assets/53d5c1f8-8fbc-4e0f-bd62-db16797492b0

Slideflow is tested on Linux-based systems (Ubuntu, CentOS, Red Hat, and Raspberry Pi OS) and macOS (Intel and Apple). Windows support is experimental.

Requirements

  • Python >= 3.7 (<3.10 if using cuCIM)

  • PyTorch (1.9+) or Tensorflow (2.5-2.11)

    • Core functionality, including tile extraction, data processing, and tile-based model training, is supported for both PyTorch and Tensorflow. Additional advanced tools, such as Multiple-Instance Learning (MIL), GANs, and pretrained foundation models, require PyTorch.

Optional

Download with pip

Slideflow can be installed either with PyPI or as a Docker container. To install via pip:

# Update to latest pip
pip install --upgrade pip wheel

# Current stable release, Tensorflow backend
pip install slideflow[tf] cucim cupy-cuda11x

# Alternatively, install with PyTorch backend
pip install slideflow[torch] cucim cupy-cuda11x

The cupy package name depends on the installed CUDA version; see here for installation instructions. cucim and cupy are not required if using Libvips.

Run a Docker container

Alternatively, pre-configured docker images are available with cuCIM, Libvips, and either PyTorch 1.11 or Tensorflow 2.9 pre-installed. Using a preconfigured Docker container is the easiest way to get started with compatible dependencies and GPU support.

To run a Docker container with the Tensorflow backend:

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

To run a Docker container with the PyTorch backend:

docker pull jamesdolezal/slideflow:latest-torch
docker run -it --shm-size=2g --gpus all jamesdolezal/slideflow:latest-torch

Build from source

To build Slideflow from source, clone the repository from the project Github page:

git clone https://github.com/slideflow/slideflow
cd slideflow
conda env create -f environment.yml
conda activate slideflow
python setup.py bdist_wheel
pip install dist/slideflow* cupy-cuda11x

Extensions

The core Slideflow package is licensed under the Apache-2.0 license. Additional functionality, such as pretrained foundation models, are distributed in separate packages according to their licensing terms. Available extensions include:

These extensions can be installed via pip. The GigaPath feature extractor has additional, more restrictive dependencies that must be installed separately.

# Install Slideflow-GPL and Slideflow-NonCommercial
pip install slideflow-gpl slideflow-noncommercial

# Install GigaPath dependencies, if desired
pip install slideflow-noncommercial[gigapath] git+ssh://git@github.com/prov-gigapath/prov-gigapath

Note

The Slideflow-GPL and Slideflow-NonCommercial extensions are not included in the default Slideflow package due to their licensing terms. Please review the licensing terms of each extension before use.

PyTorch vs. Tensorflow

Slideflow supports both PyTorch and Tensorflow, with cross-compatible TFRecord storage. Slideflow will default to using PyTorch if both are available, but the backend can be manually specified using the environmental variable SF_BACKEND. For example:

export SF_BACKEND=tensorflow

cuCIM vs. Libvips

By default, Slideflow reads whole-slide images using cuCIM. Although much faster than other openslide-based frameworks, it supports fewer slide scanner formats. Slideflow also includes a Libvips backend, which adds support for *.scn, *.mrxs, *.ndpi, *.vms, and *.vmu files. You can set the active slide backend with the environmental variable SF_SLIDE_BACKEND:

export SF_SLIDE_BACKEND=libvips

Warning

A bug in the pixman library (version=0.38) will corrupt downsampled slide images, resulting in large black boxes across the slide. We have provided a patch for version 0.38 that has been tested for Ubuntu, which is provided in the project Github page (pixman_repair.sh), although it may not be suitable for all environments and we make no guarantees regarding its use. The Slideflow docker images already have this applied. If you are installing from source, have pixman version 0.38, and are unable to apply this patch, the use of downsampled image layers must be disabled to avoid corruption (pass enable_downsample=False to tile extraction functions).