Registry / ai-ml / scvi-tools

scvi-tools

JSON →
library1.4.3pypypi✓ verified 90d ago

scvi-tools provides a suite of deep learning models for the deep probabilistic analysis of single-cell omics data. It is built on PyTorch and AnnData, offering robust methods for tasks like dimensionality reduction, batch correction, and differential expression. The library is actively developed, releasing frequent minor versions and occasional major updates.

pip install scvi-tools
INSTALL
IMPORT
SIG · SCVI-TOOLS
S
scvi-tools
ai-mlpythonv1.4.3
Install
—
Import
—
Disk
—
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
build_error
glibc
py 3.10–3.920 runs
timeout
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

scvi
✓ import scvi
SCVI
✓ from scvi.model import SCVI
✗ from scvi import SCVI
Models were moved to submodules (e.g., `scvi.model`) in version 1.0.0.
setup_anndata
✓ from scvi.data import setup_anndata
✗ scvi.data.setup_anndata(adata, ...)
While `scvi.data.setup_anndata` works, importing directly can make code cleaner. More importantly, pre-1.0.0 versions didn't explicitly require this step, leading to common errors.

This quickstart demonstrates the core workflow: loading an AnnData object, preparing it with `scvi.data.setup_anndata`, initializing and training an `SCVI` model, and then extracting the latent representation and normalized expression. The setup_anndata step is crucial for all scvi-tools models.

import scvi import scanpy as sc import numpy as np # For reproducibility scvi.settings.seed = 0 # Load a dataset # In a real scenario, you'd load your own AnnData object # For this example, we'll use a built-in dataset adata = scvi.data.pbmc_dataset() # Required step: set up AnnData for scvi-tools models # This registers the data with scvi-tools, specifying layers, batch keys, etc. scvi.data.setup_anndata(adata, layer="counts", batch_key="batch") # Initialize the SCVI model model = scvi.model.SCVI(adata, n_latent=30, n_layers=2) # Train the model # This can take several minutes depending on hardware and dataset size model.train() # Get latent representation and store it in adata.obsm adata.obsm["X_scVI"] = model.get_latent_representation() # Get normalized expression and store it in adata.layers adata.layers["scvi_normalized"] = model.get_normalized_expression(transform_batch="_scvi_batch_0") print(f"Latent representation shape: {adata.obsm['X_scVI'].shape}") print(f"Normalized expression layer shape: {adata.layers['scvi_normalized'].shape}") # Further analysis could involve using scanpy on the latent space # sc.pp.neighbors(adata, use_rep="X_scVI") # sc.tl.umap(adata) # sc.pl.umap(adata, color=["cell_type", "batch"])
scvi --version
Debug
Known issues
breakingscvi-tools 1.0.0 introduced a major API overhaul, transitioning from a custom `Vaedata` object to `AnnData` as the primary data structure. This required significant code changes for users migrating from pre-1.0.0 versions.
fix
Migrate code to use `AnnData` objects. All models now require `scvi.data.setup_anndata` to be called on the AnnData object before instantiation. Model classes were moved, e.g., `scvi.SCVI` became `scvi.model.SCVI`.
affects: <1.0.0 to 1.0.0+
gotchaGPU support requires careful installation of `pytorch` with the correct CUDA version. Mismatched CUDA versions between your system, `pytorch` wheel, and potentially `cudatoolkit` in a Conda environment can lead to `RuntimeError: CUDA error` or models running slowly on CPU.
fix
Follow the official installation instructions carefully, especially for GPU. Consider using Conda for better dependency management (`conda install -c pytorch -c conda-forge -c bioconda scvi-tools` will typically resolve PyTorch and CUDA dependencies correctly).
affects: All
gotchaForgetting to call `scvi.data.setup_anndata` before initializing any model is a common mistake for users familiar with older versions or other single-cell libraries. This step is mandatory for all models since 1.0.0.
fix
Always call `scvi.data.setup_anndata(adata, layer="counts", batch_key="batch")` (adjusting `layer` and `batch_key` as needed) on your `AnnData` object before passing it to `scvi.model.SCVI` or other model constructors.
affects: 1.0.0+
deprecatedThe `transform_batch` argument in `model.get_normalized_expression()` was deprecated and then removed in version 1.4.0. Using it will raise an error.
fix
Remove the `transform_batch` argument from `model.get_normalized_expression()`. If you need batch-specific normalization, consider handling it downstream or using other model features.
affects: 1.4.0+
Errors
Common errors & fixes
AttributeError: 'AnnData' object has no attribute '_scvi_data_registry'
Attempting to initialize an scvi-tools model on an AnnData object that has not been prepared with `scvi.data.setup_anndata`.
fix
Call `scvi.data.setup_anndata(adata, layer="counts", batch_key="batch")` before initializing your model.
ImportError: cannot import name 'SCVI' from 'scvi'
Trying to import a model class directly from the top-level `scvi` module, a pattern common in pre-1.0.0 versions.
fix
Model classes are now in submodules. For example, `SCVI` is imported via `from scvi.model import SCVI`.
RuntimeError: CUDA error: device-side assert triggered
This usually indicates an issue with the GPU setup, such as mismatched CUDA versions between PyTorch and your system, or running out of GPU memory.
fix
Verify your PyTorch and CUDA installation. Use `torch.cuda.is_available()` and `torch.cuda.get_device_name(0)`. If using Conda, reinstall `scvi-tools` with `conda install -c pytorch -c conda-forge -c bioconda scvi-tools`. For 'out of memory', try reducing `batch_size` during training.
TypeError: 'numpy.ndarray' object is not callable
This can occur if you mistakenly try to call an `AnnData` layer or observation field (e.g., `adata.X`) as a function, often after a data transformation.
fix
Ensure you are accessing AnnData attributes correctly (e.g., `adata.X`, `adata.layers['counts']`, `adata.obs['cell_type']`) and not trying to call them like functions. Verify the data type of the attribute you're accessing.
Upgrade
Version history
1.4.3latest on PyPI · released May 12, 2026
Audit
Dependencies
anndatarequiredPrimary data structure for single-cell data.
scanpyoptionalCommonly used for preprocessing and visualization in the single-cell ecosystem.
pytorchrequiredDeep learning backend for all models.
Agent activity
15 hits · last 30 days
node
14
OpenAI (training)
1
Resources
scvi-tools — pip install scvi-tools · libregistry