Prov-GigaPath: a whole-slide foundation model for digital pathology

A slide-level embedding from a gigapixel image

Prov-GigaPath is described as a whole-slide foundation model for digital pathology built from real-world data, and the architecture is the reason it exists. A single tissue slide in digital pathology is far too large to feed to an image model directly, so the approach is to encode tiles and then combine them into one representation of the slide.

The repository is the official code and model release for the GigaPath paper published in Nature in 2024, with the model weights on the Hugging Face Hub under prov-gigapath. The author list runs to two pages of names and includes Hanwen Xu and Naoto Usuyama as equal contributors, with institutions represented from Microsoft Research and elsewhere in the accompanying material.

The model family table in the README is the best summary of where the project is. GigaPath itself is the whole-slide foundation model with the Nature 2024 paper. GigaPath-Flash is the efficient variant, released with an arXiv preprint from 2026. GigaTIME is a different task in the same family, spatial proteomics prediction from H&E, published in Cell in 2026, and GigaTIME-Flash is its efficient counterpart. All four carry the Apache-2.0 licence, which is unusually permissive for a biomedical model and removes the negotiation step most academic weights require.

The Python package is published as gigapath with version 0.1.0 in pyproject.toml and requires-python of 3.9 or newer. The package configuration includes only the gigapath package directory, excluding assets, benchmarks, docs, scripts, tests and outputs from the distribution.

Two encoders and the dimension that decides your memory budget

The README describes the Flash variant in enough detail to understand the whole model, because the two encoders are the same in both versions and only their size differs.

The tile encoder processes individual patches of the slide. In the original GigaPath it is a DINOv2 encoder producing 1536-dimensional tile embeddings. The slide encoder then aggregates those into a single slide representation, and in the original it is 12 layers at 768 dimensions. The naming in the Flash release makes the contrast explicit: the slide encoder uses a LongNet backbone with 12 layers and a 384-dim hidden size, around 21M parameters, paired with a 384-dim DINOv2-small tile encoder, ViT-S/16, at around 22M parameters. The README states that both the slide encoder hidden dimension and the input tile-embedding dimension are 384 in the Flash variant.

The architecture names are what you pass to the loader: gigapath_slide_enc12l384d for the slide encoder with input_dim=384 and latent_dim=384, and gigapath_tile_enc_dinov2s for the tile encoder. The demo scripts in the repository follow that split, with separate loaders for the tile encoder and the slide encoder and a multi-predict slide check.

Weight packaging is also specified, and it matters when you write your own loading code. The tile encoder ships as a config.json plus a pytorch_model.bin in the timm format. The slide encoder ships as a single slide_encoder.pth whose contents are a model key, and it is encoder only, with no decoder included.

The environment assumes an A100 with CUDA

The install instructions are short and start with a hardware statement: an NVIDIA A100 Tensor Core GPU machine, with the CUDA toolkit enabled.

The repository is cloned and the environment created with conda:

git clone https://github.com/prov-gigapath/prov-gigapath
cd prov-gigapath

conda env create -f environment.yaml
conda activate gigapath
pip install -e .

The requirements.txt shows how tightly pinned this stack is. xformers is fixed at 0.0.18, huggingface-hub at 0.20.2, transformers at 4.36.2, torchmetrics at 0.10.3, packaging at 23.2 and ninja at 1.11.1.1. Alongside those are the looser entries you would expect: timm, webdataset for sharded data loading, fairscale, wandb, h5py, iopath, fvcore, omegaconf, einops, pillow, pandas, numpy, scikit-learn, scikit-survival and lifelines, with tensorboard for experiment tracking.

The presence of webdataset, fairscale and wandb in the requirements is the giveaway about how this is meant to be trained rather than merely used. This is a training-oriented release. The precision of those pins also tells you that upgrading anything is not a casual operation, since transformers and huggingface-hub in particular have moved a long way since those versions.

For inference only, you would install a smaller subset, but the README does not offer a separate inference requirements file, so the honest answer is that the documented path is the full environment.

Gated weights, a read-only token and one specific error

The weights are not openly downloadable, and the README is explicit about the two steps involved.

First, you have to agree to the terms to access the models on the Hugging Face Hub. Once you have access, you set your read-only token as an environment variable:

export HF_TOKEN=<huggingface read-only token>

The README then names the failure you get if you skip this. Without the token you may hit:

ValueError: We have no connection or you passed local_files_only, so force_download is not an accepted option.

The error message is worth reading carefully because it is misleading at first glance. It mentions local_files_only, which suggests you set an offline flag, but the real cause is that the gated download needs credentials and there is no connection to fetch the model anonymously. Anyone who hits this will probably try local_files_only first and make things worse.

A read-only token is the right credential to use here, and it matches how the weights are consumed. Nothing in the README describes a write scope being needed, so there is no reason to mint a token with more access than the download requires.

The terms agreement is the other half of the gate. Unlike a model published under an open licence with a click-through, this one asks for an explicit acceptance before the files are reachable, which is a reasonable practice for a clinical foundation model and is worth factoring into any procurement conversation.

Converting raw checkpoints into the release format

If you want to fine-tune rather than only run inference, you need checkpoints in the release format, and the README explains how to produce them.

Raw pretraining checkpoints contain parameters that downstream use does not need, so a conversion step strips them. The slide encoder script removes the MAE decoder and the masking parameters, and the tile encoder script converts a DINOv2-small student checkpoint into the timm and Hugging Face format, dropping the DINOv2 self-supervised heads and writing config.json plus pytorch_model.bin:

python scripts/convert_slide_encoder_checkpoint.py <pretrain_checkpoint.pth> <slide_encoder.pth>

python scripts/convert_tile_encoder_checkpoint.py <dinov2_student.pth> <tile_encoder_dir>

Both outputs mirror the format of the original Prov-GigaPath slide_encoder.pth and tile encoder, which is the point: a converted Flash checkpoint is loaded by exactly the same code path as the published one. That matters more than it sounds, because the alternative is a bespoke loader per checkpoint and a second set of bugs.

The repository listing shows where the rest of the work lives. There is a finetune/ directory, a linear_probe/ directory, a dataset_csv/ directory, a data/ directory, a scripts/ directory and a demo/ directory. The demo folder contains the loading and tiling scripts and two notebooks, one walking through running the pretrained model and one showing embedding visualisation with PCA.

For a labelling-driven evaluation, the linear_probe/ path is the one to read first. A linear probe over frozen embeddings is the cheapest way to find out whether a slide representation carries the signal you need, and it avoids the cost of a full fine-tune before you know the model is useful for your tissue types.

Where the practical work actually starts

The most useful document for a new user is not in the root of the repository. It is the WSI preprocessing and tiling guide at gigapath/preprocessing/preprocessing.md, announced in July 2024, which walks through setting up the environment and preprocessing whole slide images before the model ever sees them.

That is a meaningful signal about the shape of this project. A whole-slide model does not accept a PNG. It needs tiling, a tile manifest, and a mapping back to slide coordinates, and the preprocessing step is where a great deal of the effort lives in practice. The repository's data/ and dataset_csv/ directories, plus the webdataset dependency, are consistent with a sharded tile pipeline rather than simple image folders.

Two other pieces of the timeline are worth noting. In September 2024 the project shared the PCA embedding visualisation notebook, which is a quick way to see whether the representations separate anything meaningful in your own data. In July 2026 the maintainers released the Flash variants for faster, more memory-efficient inference and finetuning, which is the response to the fact that the original model is large enough to be a problem on anything short of a datacentre GPU.

The limitations are the ordinary ones of research code with a small team. There are no GitHub releases, so there is no versioned artifact and no changelog beyond the commit history, and the last push was on 2026-08-07. The Flash variants are the answer for teams with less GPU memory, but they are separate checkpoints rather than a smaller file for the same model, so you choose a lineage and stick with it. And the upstream paper and the Cell and Nature publications are the authoritative description of what the model was trained on and validated against, which matters more than the code when you are evaluating it for clinical or research use.

Editorial conclusion

Prov-GigaPath fits a pathology group that needs slide-level representations from real diagnostic data, has an A100 class GPU and CUDA available, and is prepared to sign the Hugging Face terms to obtain gated weights. It is the wrong choice for a workstation without a data centre GPU, for a team that needs a documented, reproducible preprocessing pipeline beyond the guide in gigapath/preprocessing/preprocessing.md, or for anyone needing a versioned public release, since the repository has no GitHub releases and the last push was on 2026-08-07. Before starting, confirm the checkpoint access works with your HF_TOKEN, decide between the full model and the Flash variant for your memory budget, and read the finetune/ and linear_probe/ directories, since they are where the evaluation recipes live.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. prov-gigapath/prov-gigapath on GitHub
4. README