scvi-tools: probabilistic models for single-cell and spatial omics in Python
Deep probabilistic analysis of single-cell and spatial omics data
At a glance
- What is it?
- scvi-tools packages dozens of variational-inference models behind one AnnData-shaped API. It is the right tool when you want a latent representation with a likelihood attached, and the wrong tool when you want a fast, assumption-light embedding.
- Who is it for?
- Adopt scvi-tools if you need a latent space you can sample from, integrate batches across experiments, or deconvolve spatial spots, and if you already work in AnnData and can supply a GPU. Do not adopt it if a deterministic PCA and neighbor graph already answer your question, or if you cannot install a PyTorch build matched to your hardware.
- Can I use it commercially?
- Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap scvi-tools fills between Scanpy and a bespoke model
Scanpy gives you a deterministic pipeline: normalize, log, select highly variable genes, run PCA, build a neighbor graph. That pipeline is fast and has few knobs, but the embedding it produces has no likelihood. You cannot sample from it, you cannot put a prior on it, and you cannot ask it for a posterior over a batch effect. scvi-tools exists for the cases where that matters. The README describes it as a package for probabilistic modeling and analysis of single-cell omics data, built on PyTorch and AnnData, and lists the task families it covers: dimensionality reduction, data integration, automated annotation, factor analysis, doublet detection, and spatial deconvolution. Each of those is a model with its own generative assumptions rather than a fixed preprocessing recipe. The intended user is therefore not every analyst who touches a count matrix. It is the analyst who has a question that can be phrased as inference over latent variables, and who is willing to accept the training cost and the model-selection burden that come with that framing.
What the architecture actually commits you to
The README states that all model implementations share a high-level API that interacts with Scanpy and includes standard save and load functions plus GPU acceleration. The building blocks underneath are PyTorch Lightning and Pyro, per the same document. That combination is the real design decision. AnnData is the data contract, so your counts, batch labels, and covariates live in the same object you already pass to Scanpy. PyTorch Lightning is the training contract, so a model is a module with a training step, an optimizer configuration, and a checkpoint format rather than a script. Pyro is the inference contract, so models that need custom variational distributions or stochastic control flow are not forced into a single encoder shape. The README points to a codebase overview page in the documentation for the package structure and to a separate skeleton repository, simple-scvi, as a starting point for developing and deploying new models. That skeleton is the clearest signal of intent: the project is positioned as a framework for writing models, not only a catalog of finished ones. The cost of that positioning is that the framework surface is larger than a preprocessing library, and a user who only wants one embedding still has to navigate model classes, training loops, and checkpoint files.
Installing scvi-tools and the PyTorch version trap
The README gives two installation paths. For conda, `conda install scvi-tools -c conda-forge`. For pip, `pip install scvi-tools`. Immediately after, it adds a warning that matters more than either command: install a version of PyTorch compatible with your GPU, if applicable. scvi-tools does not pin that for you in a way that can anticipate every driver and CUDA combination, so the practical sequence is to install PyTorch first from the index that matches your hardware, then install scvi-tools, then confirm that the two agree. On a CPU-only machine the pip path is the simpler one. On a shared cluster the conda path is usually preferable because conda-forge carries the compiled dependencies. The README also names the supporting resources rather than burying them: tutorials, API reference and installation guides in the documentation, a Discourse forum for usage discussion, GitHub issues for bug reports, and a contributing guide for patches. If you find a model useful for your research, the README asks you to cite the corresponding publication for that model, in addition to the library itself. That citation requirement is worth reading before you build a pipeline around a model whose paper you have not checked.
Where the probabilistic framing becomes a liability
A generative model is only as good as its assumptions, and scvi-tools asks you to choose among many models with different assumptions. The README lists the task families but does not, in the material available here, tell you which model to pick for a given assay or how sensitive results are to that choice. That selection step is left to the user guide and to the publications behind each model. There are concrete consequences. Training a variational model takes longer than running PCA, and the README's GPU acceleration claim implies that the intended experience assumes a GPU; on CPU-only hardware the practical cost rises. Latent spaces from different models are not interchangeable, so a downstream clustering result depends on which model produced the embedding, and swapping models invalidates comparisons rather than refining them. Reproducibility also depends on more than a random seed: checkpoint files, the library version, and the PyTorch version all participate, which is why the README's emphasis on standard save and load functions matters. Finally, scvi-tools is the wrong tool when your question is descriptive. If you want a quick look at which cell types are present, a deterministic pipeline answers that in minutes and with fewer decisions to defend.
Scanpy is not a competitor, and that is the point
The obvious alternative for a Python user is Scanpy alone. The difference in approach is straightforward: Scanpy computes a fixed sequence of transformations and a deterministic embedding, while scvi-tools fits a generative model and returns a posterior. Scanpy will not give you a batch-corrected latent space with an explicit likelihood, and scvi-tools will not give you the speed or the near-zero configuration burden of PCA. The two are designed to interoperate, since scvi-tools' high-level API interacts with Scanpy and AnnData is the shared container, so the realistic choice is not one or the other but where in the pipeline you switch. A second alternative, for users who want probabilistic modeling but not this framework, is to write a model directly in Pyro or PyTorch Lightning. scvi-tools' answer to that is the skeleton repository and the claim that its building blocks support rapid development of novel models. Whether the framework saves you time depends on how close your model is to the ones already implemented; for a genuinely new generative assumption, the abstraction may cost more than it returns.
Maintenance, licensing and the citation obligation
The repository is not archived, and the release history shows 1.5.1 published on 2026-09-10, with 1.5.0 and a 1.5.0.post1 in July 2026. The post-release suggests that patch-level fixes arrive between minor versions, which is normal for a library with compiled and GPU-dependent dependencies. Because scvi-tools sits on PyTorch, PyTorch Lightning, Pyro and AnnData, an upgrade can be blocked by any of them, and the README's instruction to match PyTorch to your GPU means that a scvi-tools upgrade is often also a PyTorch upgrade. Budget for that: pin versions in your environment, keep the checkpoint alongside the code that produced it, and re-run a known dataset after upgrading rather than assuming a saved model loads identically. On licensing, the repository is BSD-3-Clause, a permissive licence that generally allows use in proprietary software provided the copyright notice and disclaimer are retained. The README also notes that scvi-tools is part of the scverse project, governed under scverse and fiscally sponsored by NumFOCUS, and that the copyright line belongs to the Yosef Lab at the Weizmann Institute of Science. None of that is legal advice; if you are shipping scvi-tools inside a product, have your own counsel read the licence text and the citation expectations rather than relying on this summary.
How to decide in an afternoon
Start from the user guide and confirm that a model exists for your assay and your task, because the README's task list is a summary and not a compatibility matrix. Then check the publication for that specific model, since the README asks you to cite it and you should know what assumptions you are adopting. Install PyTorch for your hardware first, then scvi-tools, then train on a small subset of your own data before touching the full matrix. If the latent space from that small run does not separate the structure you already know is there from a Scanpy analysis, the added machinery is not buying you anything on this dataset. If it does, the checkpoint and the version pins become part of your analysis record, not an afterthought. The judgement is narrow: scvi-tools earns its cost when the posterior is the point, and it does not when the embedding is just a step toward a plot.
Editorial conclusion
Adopt scvi-tools if you need a latent space you can sample from, integrate batches across experiments, or deconvolve spatial spots, and if you already work in AnnData and can supply a GPU. Do not adopt it if a deterministic PCA and neighbor graph already answer your question, or if you cannot install a PyTorch build matched to your hardware. Before committing, verify three things: that a model exists for your assay in the user guide, that your PyTorch and CUDA combination is supported, and that the specific model you pick has a publication you are willing to cite alongside the library.
Community notes