Downloading model weights

Pretrained checkpoints are not bundled with the package. Download the ones you need once into the workspace; every later run reuses them.

Note

Run scfoundry commands from inside a workspace created by scfoundry init (any subdirectory works — the workspace is found by walking upwards, like a git repository), or pass --workspace DIR. Weights, the image cache, results and run logs all live there. See The workspace.

Downloading a model

scfoundry download --method scgpt

[PIPELINE] scFoundry | profile=standard
[WORKDIR] /home/you/my_project/runs/download/20260828-141002_scgpt/work
[PROCESS 5c/4583c5] DOWNLOAD:download_scgpt_checkpoints
scGPT_human checkpoints downloaded!

[SUCCESS] completed=1 failed=0 cached=0
[scfoundry] done (ok).

The files land in data/model_weights/scGPT/scGPT_human/. Repeat for each model you plan to use — there is no “download everything” flag, because the full set is over 70 GB and most users need two or three models.

Downloads run on the CPU in the method’s own container, so they work on a login node and can be done before you have a GPU allocation. The one thing they need is outbound network access.

Note

pca and the integration baselines (harmony, seurat_cca, seurat_rpca, scvi_denovo, scgpt_integrated) need no download of their own: scgpt_integrated starts from the scGPT checkpoint, the others train from scratch.

What gets downloaded where

Every checkpoint comes from its authors’ official release. Sizes are the on-disk footprint after extraction.

--method	Path under data/model_weights/	Size	Source
scgpt	scGPT/scGPT_human/	198 MB	Google Drive (official scGPT release)
geneformer	Geneformer/Geneformer-V2-316M/	1.2 GB	Hugging Face ctheodoris/Geneformer
scfoundation	scFoundation/models.ckpt	1.4 GB	Hugging Face genbio-ai/scFoundation
scbert	scBERT/panglao_pretrain.pth	84 MB	Google Drive (official scBERT release)
sccello	scCello/scCello-zeroshot/	43 MB	Hugging Face katarinayuan/scCello-zeroshot
langcell	LangCell/ckpt/	660 MB	Google Drive (official LangCell release)
scprint	scPRINT/medium-v1.5.ckpt	212 MB	Hugging Face jkobject/scPRINT, pinned revision, SHA-256 verified
cellfm	CellFM/CellFM_80M_weight.ckpt	987 MB	Hugging Face ShangguanNingyuan/CellFM
cellplm	CellPLM/20231027_85M.best.ckpt	865 MB	Official Dropbox share, SHA-256 verified
cellama	CELLama/all-MiniLM-L6-v2/	932 MB	Hugging Face sentence-transformers/all-MiniLM-L6-v2
genept	GenePT/*.pickle	1.4 GB	Zenodo record 10833191
scimilarity	SCimilarity/model_v1.1/	41 GB	Zenodo record 10685499
uce	UCE/ (six files plus protein_embeddings/)	17 GB	figshare (official UCE release)
c2s	C2S/C2S-Pythia-410m-cell-type-prediction/	4.6 GB	Hugging Face vandijklab/C2S-Pythia-410m-cell-type-prediction
scvi	scVI/Census2024-07-01-HomoSapiens/model.pt	410 MB	CZ CELLxGENE Census (S3)
novae	Novae/novae-human-0/	124 MB	Hugging Face prism-oncology/novae-human-0

Tip

SCimilarity and UCE dominate the total. If disk is tight, download them last and only if you need them. UCE also leaves a 2.6 GB protein_embeddings.tar.gz beside the directory it extracted to — that archive is safe to delete once the extraction has finished.

Note

scPRINT’s checkpoint was called v2-medium when the benchmark started; its authors have since renamed the same weights medium-v1.5 and released a separate 2.0 series. scFoundry downloads medium-v1.5 from a pinned Hugging Face revision, so what you get is byte-for-byte the checkpoint the paper evaluated.

Selecting a variant

Most methods store their checkpoint at a path under data/model_weights/, and --model chooses another path relative to that directory — both when downloading and when running:

scfoundry download --method novae --model Novae/novae-brain-0
scfoundry embed --method novae --model Novae/novae-brain-0 --data spatial.h5ad

If you omit --model, each method falls back to its own default; the defaults are listed in the method reference.

Two methods are exceptions:

• genept — --model is a selector, not a path. Only GenePT/ada-002 (default, 1536-dimensional) and GenePT/model-3-large (3072-dimensional) are recognised.

• langcell — the checkpoint path is fixed to LangCell/ckpt; there is no --model.

• scvi — the pretrained Census model is selected with --scvi_model rather than --model.

Placing weights manually

The download task is a convenience, not a requirement. If your cluster has no outbound network access, fetch the files on a machine that does and copy them into the same layout:

data/
└── model_weights/
    └── scGPT/
        └── scGPT_human/
            ├── args.json
            ├── best_model.pt
            └── vocab.json

Sharing weights between users

Checkpoints are read-only and identical for everyone, so a shared copy usually makes sense. Either pass it per run:

scfoundry embed --method scgpt --data cells.h5ad --weights-dir /shared/scfoundry/model_weights

or set it once in the workspace nextflow.config:

params {
    model_weights_dir = "/shared/scfoundry/model_weights"
}

Whatever it resolves to is bind-mounted at /data/model_weights inside every container, so nothing else changes. The same applies to download: with --weights-dir it fills the shared directory.

Re-running a download

Downloads are not incremental. Re-running download for a method re-fetches it, with one exception: the scVI process skips the download if model.pt already exists. If a download was interrupted, delete the partial directory before retrying.

See also

Method reference — container images, default checkpoints, and upstream versions for every model.