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
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
timeout
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.fixMigrate 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.fixFollow 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.fixAlways 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.fixRemove 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`.
fixCall `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.
fixModel 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.
fixVerify 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.
fixEnsure 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.