Installation

scFoundry has three requirements: Python for the scfoundry command, Nextflow to run the pipeline, and a container runtime to run the models. There are no per-model environments to build — every model ships as a container image that is pulled on first use.

System requirements

Requirement

Detail

Operating system

Linux, x86_64. The container images are not built for macOS or ARM.

Python

≥ 3.7, standard library only. Used by the scfoundry command, not by the models.

Nextflow

≥ 24.10, which needs Java 17 or later. Tested with 25.04, 25.10 and 26.04.

Container runtime

Apptainer, Singularity or Docker. You need exactly one; scfoundry init detects which you have.

GPU

An NVIDIA GPU with driver ≥ 525 for every task that runs a model. download, benchmark, geometry and the CPU methods (pca, genept, harmony, seurat_cca, seurat_rpca) run without one.

Disk

Roughly 20 GB for the container images you use, plus model weights — see Downloading model weights for per-model sizes.

1. Install Nextflow

Follow the official instructions. The two common routes:

Brings Java with it, which is why it is the easiest route on a machine where you do not control the system Java:

conda create -n nf-env -c conda-forge -c bioconda nextflow python=3.12
conda activate nf-env

Needs Java 17+ already on the machine:

curl -s https://get.nextflow.io | bash
mv nextflow ~/bin/          # anywhere on your PATH

If your cluster provides Nextflow as a module, use that:

module load Nextflow

Verify:

nextflow -v

nextflow version 25.10.0.5972

2. Check your container runtime

apptainer --version

Apptainer needs no daemon and no root privileges, which makes it the right choice on a shared cluster. Singularity works identically.

docker --version
docker run --rm --gpus=all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

The second command confirms that the NVIDIA Container Toolkit is installed and that containers can see your GPUs. If it fails, install nvidia-container-toolkit before continuing.

3. Install scFoundry

Install into the same environment that provides nextflow, so that one conda activate (or one module load) gives you both:

pip install scfoundry                                       # release, from PyPI
pip install git+https://github.com/Svvord/scFoundry.git     # or the latest from GitHub

scfoundry --version
scfoundry info

scfoundry  0.2.0
pipeline   /home/you/.conda/envs/nf-env/lib/python3.12/site-packages/scfoundry/pipeline
nextflow   25.10.0.5972 (/home/you/.conda/envs/nf-env/bin/nextflow)
workspace  (none)  -- run 'scfoundry init' to create one

pipeline is the Nextflow code bundled inside the package. workspace is empty until the next step.

Note

Some HPC systems set PYTHONNOUSERSITE, which makes pip install --user packages invisible. Install into a conda or virtual environment instead of --user.

4. Create a workspace

A workspace is a directory that holds your configuration, weights, image cache, results and run logs. Create one wherever you have disk space:

scfoundry init my_project
cd my_project

[scfoundry] workspace: /home/you/my_project
[scfoundry] wrote my_project/nextflow.config (container runtime: apptainer)
[scfoundry] pipeline:  /home/you/.conda/envs/nf-env/lib/python3.12/site-packages/scfoundry/pipeline
  nextflow   25.10.0.5972 (/home/you/.conda/envs/nf-env/bin/nextflow)
  apptainer  /usr/bin/apptainer
  GPU        nvidia-smi found but no GPU visible (fine on a login node)
  python     3.12.14 (/home/you/.conda/envs/nf-env/bin/python3.12)

Next steps:
  cd my_project
  scfoundry download --method scgpt
  scfoundry list methods

init picks the container runtime it finds on PATH; pass --runtime docker to choose explicitly. The environment report tells you now, rather than twenty minutes into a run, whether Nextflow, the runtime and a GPU are visible. What the workspace contains and how to adjust it is on The workspace.

5. Verify with the smallest real run

Fetch the demo data (about 112 MB) and embed it with the PCA reference. PCA needs no checkpoint and no GPU, so this tests the container runtime and the bind mounts without a multi-gigabyte download:

mkdir -p demo
for f in colon_1000 colon_50 liver_1shot_support liver_1shot_query; do
  curl -L -o demo/$f.h5ad https://github.com/Svvord/scFoundry/raw/main/data/demo/$f.h5ad
done

scfoundry embed --method pca --data demo/colon_1000.h5ad

Note

The first run of any method pulls its container image, which can take several minutes and a few gigabytes. The image is cached under cache/.shared/nxf_singularity/ in the workspace (or wherever --cache-dir points) and reused by every later run, so this cost is paid once per method.

[PIPELINE] scFoundry | profile=standard
[WORKDIR] /home/you/my_project/runs/embed/20260828-230006_pca_colon_1000/work
[PROCESS d5/d5baf6] EMBED:embed_by_pca (colon_1000)

[SUCCESS] completed=1 failed=0 cached=0
[scfoundry] task=embed method=pca input=colon_1000
[scfoundry] workspace: /home/you/my_project
[scfoundry] run directory: runs/embed/20260828-230006_pca_colon_1000
[scfoundry] done (ok).

On success you have:

results/embeddings/pca/colon_1000.h5ad

Read it back to confirm the embedding is there:

import anndata as ad

adata = ad.read_h5ad("results/embeddings/pca/colon_1000.h5ad")
print(adata.shape)        # (1000, 50)
print(adata.X[:3, :5])

If that works, your installation is sound and you can move on to real models.

Developer install

To work on the pipeline itself, clone the repository and install it in editable mode. The checkout then doubles as a workspace — data/demo/ is already there, and scfoundry resolves the pipeline to the checkout rather than to the bundled copy:

git clone https://github.com/Svvord/scFoundry.git
cd scFoundry
pip install -e .
scfoundry init .

Upgrading and uninstalling

pip install -U scfoundry
pip uninstall scfoundry

Neither touches a workspace: weights, caches, results and run logs stay where they are, and a newer scfoundry picks up an existing workspace as it is.

Next steps