Installation

You need Python 3.12 or newer. We recommend managing dependencies in a project-specific virtual environment using uv, to avoid dependency conflicts with the rest of your system.

Development install

spatialrefinery is not yet published to PyPI. Install the latest development version directly from GitHub:

uv

uv add git+https://github.com/peng-lab/spatialrefinery.git

pip

pip install git+https://github.com/peng-lab/spatialrefinery.git

Optional: CZI support

Reading Zeiss CZI images (via bioio) is an optional extra, kept separate because it pulls in additional native dependencies:

pip install "spatialrefinery[czi] @ git+https://github.com/peng-lab/spatialrefinery.git"

Without the czi extra, convert_to_ometiff still handles every other registered format (.svs, .ndpi, .tif, .tiff, .mrxs, .scn, .bif, .vms, .svslide) – only .czi requires it.

Optional: nucleus segmentation

Nucleus segmentation on H&E whole-slide images needs the segmentation extra, which pulls InstanSeg (instanseg-torch) plus rasterio, geojson and tiffslide:

pip install "spatialrefinery[segmentation] @ git+https://github.com/peng-lab/spatialrefinery.git"

It is kept optional because instanseg-torch brings torch and therefore multi-GB CUDA wheels, which most spatialrefinery uses do not need. A CUDA GPU is strongly recommended – see Nucleus segmentation to SpatialData zarr.

Verifying the install

import spatialrefinery

print(spatialrefinery.__version__)

If this prints a version string without raising an ImportError, you’re ready for the tutorials.