Table of Contents
Shortcuts

Installation

Slideflow has been tested and is supported on the following systems:

  • Ubuntu 18.04, 20.04, and 22.04

  • Centos 7, 8, and 8 Stream

Slideflow Studio, the whole-slide interface for model deployment, is additionally supported on Windows, MacOS (Intel and Apple), and Raspberry Pi OS.

Requirements

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

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

    • Multiple-Instance Learning (MIL) requires PyTorch

    • GANs require PyTorch <1.13

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/jamesdolezal/slideflow
git submodule init && git submodule update --recursive
cd slideflow
conda env create -f environment.yml
conda activate slideflow
python setup.py bdist_wheel
pip install dist/slideflow* cupy-cuda11x

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).

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