slide2vec

slide2vec encodes whole-slide images with publicly available pathology foundation models. It uses hs2p for tissue detection and tiling, and handles batching, multi-GPU execution, and embedding storage.

Install

Python 3.10 or newer is required:

pip install slide2vec

Many models need additional dependencies available through pip install "slide2vec[fm]". See the model installation guide for model-specific extras, separate environments, and upstream packages.

For gated models such as Virchow2, request access on the model's Hugging Face page and authenticate with hf auth login or an HF_TOKEN environment variable.

Embed a slide

from slide2vec import Model, PreprocessingConfig

model = Model.from_preset("virchow2")
preprocessing = PreprocessingConfig(requested_spacing_um=0.5)
embedded = model.embed_slide("/path/to/slide.svs", preprocessing=preprocessing)

tile_embeddings = embedded.tile_embeddings  # (N, 2560)
x, y = embedded.x, embedded.y               # level-0 tile coordinates

The preset supplies tile size and precision defaults. Declare spacing explicitly for models such as Virchow2 that support several scales. Use list_models() to list presets, or filter with list_models("tile"), list_models("slide"), or list_models("patient").

See getting started for preprocessing and execution settings, and the API guide for patient embeddings, image inputs, and dense grids.

Save a batch

Create a CSV manifest:

sample_id,image_path
slide-1,/data/slide-1.svs
slide-2,/data/slide-2.svs

Optional mask_path and spacing_at_level_0 columns supply a mask or correct missing or incorrect level-0 spacing. Patient-level models also require patient_id; see the manifest schema.

from slide2vec import ExecutionOptions, Model, Pipeline, PreprocessingConfig

pipeline = Pipeline(
    model=Model.from_preset("virchow2"),
    preprocessing=PreprocessingConfig(requested_spacing_um=0.5),
    execution=ExecutionOptions(output_dir="outputs/run"),
)
result = pipeline.run(manifest_path="/path/to/slides.csv")

Runs use all available GPUs by default; set ExecutionOptions(num_gpus=2) to limit them. Embeddings are saved as .pt tensors with metadata sidecars. Use ExecutionOptions(output_format="npz") for NumPy archives. The output guide describes directories, shapes, coordinates, and progress records.

Add region_tile_multiple=6 to the preprocessing config to group tiles into 6×6 regions. These produce (num_regions, 36, feature_dim) tensors in hierarchical_embeddings/; see hierarchical features.

The same batch workflow is available from the terminal:

slide2vec /path/to/config.yaml

The CLI guide provides a complete config example, overrides, and resume instructions.

Docker

docker pull waticlems/slide2vec:latest
docker run --rm -it \
    -v /path/to/your/data:/data \
    -e HF_TOKEN \
    waticlems/slide2vec:latest

Set HF_TOKEN in your shell before starting the container.

Metadata

Release files for slide2vec 6.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for slide2vec 6.3.0
File	Size	Uploaded
slide2vec-6.3.0.tar.gz	402.0 kB	Oct 1, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for slide2vec 6.3.0
File	Interpreter	ABI	Platform	Reset
slide2vec-6.3.0-py3-none-any.whl 274.5 kB Oct 1, 2026	Python 3	none	any	Details

Total release size: 676.5 kB

Release files / slide2vec-6.3.0.tar.gz

Download URL	slide2vec-6.3.0.tar.gz
Size	402.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`78417e40bdf993acf38d254d8b8d3cbb1aa83260374420f1b2e6adfc47ea56a9`
BLAKE2b-256 checksum How to use checksums	`2f250eac4feea3f17298524016aff7fac61a15e0418c8dd1e9cce34bd82b5126`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`

Release files / slide2vec-6.3.0-py3-none-any.whl

Download URL	slide2vec-6.3.0-py3-none-any.whl
Size	274.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`7f23a368760404096f7f80ee02b8b7ff44f67247ffb6c01b7e1492abf82f10d0`
BLAKE2b-256 checksum How to use checksums	`4076d0d3de26cab9cd7c69ad2d92987fb8a10f74cd921499b37d7d0d3bef5719`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`