Install & Compatibility
Where this runs
tested against v1.11.5 · pip install
no network on importno background threads
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.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 29.1s · import 8.173s · 757MB
803MB installed
● package 803MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
scanpy
✓ import scanpy as sc
The conventional alias for Scanpy.
AnnData
✓ import anndata as ad
While AnnData is a core concept, it's typically imported as 'ad' separately, or accessed via Scanpy functions returning AnnData objects.
This quickstart demonstrates a typical single-cell RNA sequencing (scRNA-seq) analysis workflow using Scanpy. It covers loading a dataset, essential preprocessing steps (filtering, normalization, log-transformation, highly variable gene selection, regression, scaling), dimensionality reduction (PCA, UMAP), and clustering (Leiden). Finally, it visualizes the UMAP embedding colored by cluster and QC metrics. The `pbmc3k` dataset is used as a readily available example.
import scanpy as sc
import matplotlib.pyplot as plt
# Set verbosity for Scanpy (0: errors, 1: warnings, 2: info, 3: hints)
sc.settings.verbosity = 3
# Load a sample dataset (e.g., pbmc3k from 10x Genomics)
# This downloads the data if not present in the datasetdir
adata = sc.datasets.pbmc3k()
# Basic preprocessing pipeline
sc.pp.filter_cells(adata, min_genes=200)
sc.pp.filter_genes(adata, min_cells=3)
sc.pp.normalize_total(adata, target_sum=1e4)
sc.pp.log1p(adata)
sc.pp.highly_variable_genes(adata, min_mean=0.0125, max_mean=3, min_disp=0.5)
adata = adata[:, adata.var.highly_variable]
sc.pp.regress_out(adata, ['total_counts', 'pct_counts_mt'])
sc.pp.scale(adata, max_value=10)
# Dimensionality reduction and clustering
sc.pp.pca(adata)
sc.pp.neighbors(adata, n_neighbors=10, n_pcs=40)
sc.tl.umap(adata)
sc.tl.leiden(adata)
# Visualization
sc.pl.umap(adata, color=['leiden', 'n_genes_by_counts', 'total_counts'], show=False)
plt.tight_layout()
plt.show()
Debug
Known issues
breakingScanpy 1.12.0 removed support for Python versions older than 3.12 and now requires anndata>=0.10. Users on older Python environments will need to upgrade. Scanpy 1.10.4 also removed Python 3.9 support.fixUpgrade Python to 3.12 or newer. Ensure `anndata` is updated to at least version 0.10. `pip install 'scanpy>=1.12.0'` will manage `anndata` dependencies appropriately.
affects: 1.10.4, 1.12.0 and later
gotchaDirectly using Scanpy's internal (non-public) APIs is not officially supported and may lead to breaking changes in minor or patch releases. Stick to the documented public API.fixRefer to the official API documentation for supported functions and classes. If a desired feature is not in the public API, consider opening an issue on the Scanpy GitHub repository.
affects: All versions
gotchaReproducibility of `sc.tl.leiden` clustering results, even with `random_state` set, has been reported to be inconsistent between different Scanpy minor versions (e.g., 1.9.3 vs 1.10.4). This may be due to changes in underlying dependencies like `numpy` or `sc.pp.neighbors`.fixFor critical reproducibility, tightly pin all major dependencies (Scanpy, anndata, numpy, scikit-learn, leidenalg, igraph). Be aware that perfect bit-for-bit reproducibility across all environments might be challenging. Document your full environment using `pip freeze` or similar.
affects: Versions 1.10.0 and later (potentially earlier for specific dependency combinations)
deprecatedThe `scanpy.__version__` attribute is deprecated. Use `scanpy.version()` instead.fixReplace `sc.__version__` with `sc.version()` to retrieve the library version.
affects: 1.11.5 and later
deprecatedSome functions within `scanpy.pp` (preprocessing module) are raising `FutureWarning` due to upcoming changes.fixPay attention to `FutureWarning` messages in your console output and adapt your code to the suggested new patterns or parameters as indicated in the warnings or release notes.
affects: 1.11.0.dev11+g0cfd0224 and later (pre-release leading to 1.11.0)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'scanpy'
Scanpy is not installed in the current Python environment.
fixInstall Scanpy using pip: `pip install scanpy`.
ImportError: cannot import name 'is_categorical' from 'pandas.api.types'
The 'is_categorical' function has been deprecated in pandas 2.0 and removed in later versions.
fixDowngrade pandas to version 1.5.3: `pip install pandas==1.5.3`.
ImportError: cannot import name 'colormaps' from 'matplotlib'
The 'colormaps' module is not available in older versions of matplotlib.
fixUpgrade matplotlib to version 3.7 or newer: `pip install 'matplotlib>=3.7'`.
ImportError: cannot import name 'Literal' from 'scanpy._compat'
The 'scanpy._compat' module is not found, possibly due to an outdated or incomplete installation.
fixEnsure Scanpy is properly installed and up to date: `pip install --upgrade scanpy`.
AttributeError: module 'scanpy' has no attribute 'settings'
The Scanpy package is not recognized correctly, possibly due to an incorrect installation or import.
fixVerify that Scanpy is installed correctly and imported as `import scanpy as sc`.
Upgrade
Version history
1.12.4latest on PyPI · released Aug 27, 2026
Audit
Dependencies
anndatarequiredCore data structure for annotated data matrices. Scanpy is built around AnnData objects.
igraphoptionalRequired for some clustering algorithms, specifically when using 'leiden' algorithm with the `scanpy[leiden]` extra.
leidenalgoptionalRequired for Leiden clustering algorithm with the `scanpy[leiden]` extra.
daskoptionalEnables out-of-core workflows and parallel processing for some functions, especially with large datasets.