Install scGPT 0.2.4 for Single Cell AI [Guide]

Here’s the bit most write-ups bury: scGPT’s reference-mapping index over more than 33 million cells fits in under 1GB of memory, and similarity search for 10,000 query cells finishes in under a second on GPU (project README note, 2023.09.05). Under 1GB index. Sub-second search. Worth the dependency mess.

This guide gets scGPT 0.2.4 – latest on PyPI as of March 31, 2025 – installed, checkpointed, and verified. Not another cell-type annotation tour. The path that survives real machines.

Bo Wang lab model. Nature Methods 2024. Pretrained across a repository of over 33 million cells. You install the Python package, drop a checkpoint folder on disk, call into scgpt.tasks. Embedding, annotation, integration, perturbation-style transfer – after the env stops fighting you.

System requirements before you touch pip

Packaging is loose on hardware, strict on libraries.

If you’re only embedding today, don’t buy a second GPU for the install step alone. Fine-tune memory is the cliff – inference and embed_data are far kinder.

Official download source for single cell AI scGPT

Use these URLs only:

• Code + model zoo: github.com/bowang-lab/scGPT
• Package registry: pypi.org/project/scgpt – install 0.2.4
• Docs install page defers to GitHub: scgpt.readthedocs.io
• Paper: Nature Methods 21, 1470-1480 (2024)
• Default checkpoint (whole-human): Google Drive folder linked from the README model zoo (1oWh_-ZRdhtoGQ2Fw24HP41FgLoomVo-y); organ-specific and pan-cancer checkpoints listed there too

Main-branch pyproject.toml already prints version 0.2.5. That is not the PyPI build you should pin in production today (as of the 0.2.4 upload, Mar 31, 2025). README also flags Poetry install as out of sync – stick to pip.

Install scGPT 0.2.4 step by step

I stopped fighting a contaminated base env the third time scvi-tools tried to drag half the scverse stack with it. Fresh env. Always.

1. Create and activate an isolated environment:

mamba create -n scgpt python=3.10 -y
mamba activate scgpt
# conda works if you don't have mamba

2. Torch first – CZI’s released-package path pins these:

pip install torch==2.1.2 torchvision==0.16.2

3. Install scGPT 0.2.4 without forcing flash-attn. As of the 2023.11.07 README update, flash-attention is optional; the same load_pretrained helper covers CPU, plain GPU, and flash-attn backends.

pip install "scgpt==0.2.4" scanpy gdown
# If orbax/jax noise appears:
# pip install "scgpt==0.2.4" "orbax<0.1.8" scanpy gdown

4. Optional speed path only after base import works. Match flash-attn to your CUDA/torch/CPython. The old README suggestion flash-attn<1.0.5 fails to build on many 2024-2025 stacks (community threads include #15, #160, #232). Mainline optional extras even talk flash-attn 2.x – treat it as a performance add-on, not a gate.

pip install packaging ninja
# then a matching wheel or source build from Dao-AILab releases - example only

5. Missing R during install? Put it on PATH (Debian/Ubuntu sketch):

sudo apt-get update && sudo apt-get install -y r-base

Pro tip: Pin scgpt==0.2.4. Metadata still wants scvi-tools>=0.16.0,<1.0 (see main pyproject.toml / issue #260). Letting pip “helpfully” upgrade the scverse stack is how quiet envs die two weeks later.

First-time configuration: minimum viable checkpoint

Weights are not inside the wheel. You need a checkpoint directory (vocab + model files) on disk.

mkdir -p $HOME/scgpt_models && cd $HOME/scgpt_models
# whole-human folder id from the official model zoo
gdown --folder 1oWh_-ZRdhtoGQ2Fw24HP41FgLoomVo-y
# Expect a directory such as scGPT_human/ with model and vocab files

export SCGPT_MODEL_DIR=$HOME/scgpt_models/scGPT_human
# add to ~/.bashrc or your job script

No YAML control plane. No server daemon. Working env + path to that folder + AnnData with a gene-name column (feature_name on CELLxGENE-style files).

Verify the install actually works

python - <<'PY'
import scgpt
import torch
print("scgpt:", getattr(scgpt, "__version__", "unknown"))
print("torch:", torch.__version__, "cuda:", torch.cuda.is_available())
from scgpt.tokenizer.gene_tokenizer import GeneVocab
print("import path OK")
PY

Clean import. Version consistent with 0.2.4. Then smoke-test embedding on a tiny h5ad once SCGPT_MODEL_DIR is set – CZI quickstart pattern: scg.tasks.embed_data(adata, model_dir, gene_col=..., batch_size=64).

Watching a 53-million-parameter model (CZI Virtual Cells model card, scGPT v1.0) light up after an hour of packaging archaeology still feels slightly unfair. Cells shouldn’t tokenize this cleanly. And yet.

Common install errors and fixes

The catch is almost never “scGPT itself.” It’s the stack around it.

flash-attn build dies / nvcc missing / multi-hour compile. Skip it for day one. Confirm plain scgpt==0.2.4 imports. Only then chase a prebuilt wheel. Don’t sit on a source build overnight hoping a 2023 CUDA 11.7 story still matches your box.

scvi / jax / orbax resolver fights. Nuke the env. Torch first, then scgpt==0.2.4, add orbax<0.1.8 if the resolver complains. Don’t override the scvi-tools<1.0 cap “just to be current.”

Missing R binary. System R on PATH in the same shell you use for pip.

GLIBCXX / libstdc++ errors after pip “succeeds.” Older Linux images. Newer base container or upgrade OS libstdc++ – the wheel installed; the dynamic linker didn’t.

CUDA mismatch.python -c "import torch; print(torch.version.cuda)" is truth for what your torch wheel expects. Align the driver/toolkit story to that, not the other way around.

Upgrade and uninstall

# Stay on the released pin until you intentionally move
pip install -U "scgpt==0.2.4"
# When a newer PyPI release appears:
# pip install -U scgpt

pip uninstall -y scgpt
mamba deactivate
mamba env remove -n scgpt
rm -rf $HOME/scgpt_models # only if you want checkpoints gone too

Coming from 0.1.x? Rebuild the env. Partial upgrades leave half-broken imports once scvi-tools and datasets pins shift. Community image xueerchen/scgpt:0.1.7 targets that older generation – not 0.2.4.

Next: zero-shot notebooks under tutorials/zero-shot, faiss reference mapping, organ-specific checkpoints (brain, blood, pan-cancer) when your tissue prior is strong.

FAQ

Do I need flash-attn to run scGPT 0.2.4?

No. Optional since late 2023. Add it later only if you need the speed and have a matching CUDA build.

Can I deploy scGPT on a machine without an NVIDIA GPU?

Yes for load + lighter embedding. CZI’s quickstart called out an M3 MacBook with 32 GiB memory (and Colab T4). Different story if you push fine-tunes: community numbers land near ~38GB at batch 64 on an A100 40GB – shrink batch size before you assume multi-GPU.

Why does pip install scgpt keep breaking on scvi-tools or orbax?

People paste pip install scgpt into an env that already runs modern scvi. The published set still caps an older scvi-tools major (<1.0) and historically needed orbax<0.1.8. Resolver loses. Fresh Python 3.10, torch first, then scgpt==0.2.4 with the orbax cap if needed. Need bleeding-edge scvi for another project? Second environment. One stack will not happily satisfy both.

Next action: create the scgpt env, install scgpt==0.2.4, run the version/import snippet, gdown the whole-human folder, point SCGPT_MODEL_DIR at it – then open a tutorial notebook.