Installation

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.

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:

• Slideflow-GPL: GPL-3.0 licensed extensions (GitHub)

  • Includes: RetCCL, CTransPath, and CLAM.

• Slideflow-NonCommercial: CC BY-NC 4.0 licensed extensions for non-commercial use (GitHub)

  • Includes: HistoSSL, PLIP, GigaPath, UNI, BISCUIT, and StyleGAN3.

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

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