Install & Compatibility
Where this runs
tested against v0.11.4 · 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
py 3.11
✕ build_error
✓ 13.2s
py 3.12
✕ build_error
✓ 15.3s
py 3.13
✕ build_error
✓ 14.5s
py 3.9
✕ build_error
✓ 13.6s
346MB installed
● package 346MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AnnData
✓ from anndata import AnnData
✗ import anndata as ad
This quickstart demonstrates how to create an AnnData object from a sparse matrix and annotate it with observation (cell-level) and variable (gene-level) metadata using pandas DataFrames. It then prints a summary of the AnnData object and its annotations.
import anndata as ad
import numpy as np
import pandas as pd
from scipy.sparse import csr_matrix
# Create a sparse data matrix
counts = csr_matrix(np.random.poisson(1, size=(10, 5)), dtype=np.float32)
# Create observation (cell) and variable (gene) metadata
obs_data = pd.DataFrame({
'cell_type': ['T cell', 'B cell', 'T cell', 'NK cell', 'B cell', 'T cell', 'NK cell', 'B cell', 'T cell', 'NK cell'],
'patient': ['P1', 'P1', 'P2', 'P1', 'P2', 'P1', 'P2', 'P1', 'P2', 'P2']
}, index=[f'Cell_{i}' for i in range(10)])
var_data = pd.DataFrame({
'gene_name': [f'Gene_{i}' for i in range(5)],
'chromosome': ['chr1', 'chr2', 'chr1', 'chr3', 'chr2']
}, index=[f'Gene_{i}' for i in range(5)])
# Initialize an AnnData object
adata = ad.AnnData(X=counts, obs=obs_data, var=var_data)
print(adata)
print(adata.obs.head())
print(adata.var.head())
print(adata.X.shape)
Debug
Known issues
gotchaSubsetting an AnnData object (e.g., `adata_subset = adata[:, list_of_vars]`) typically returns a 'view' of the original object, not a full copy. Modifying elements of this view (except for the main data matrix `.X`) will trigger a copy-on-modify, converting the view into an independent AnnData object. However, direct modifications to `.X` on a view *can* modify the underlying original AnnData object. Always call `.copy()` explicitly on a subset (`adata_subset = adata[...].copy()`) if you intend to make independent changes.fixUse `adata_subset = adata[...].copy()` to ensure you're working with an independent copy. Be mindful when modifying `.X` directly on a view.
affects: All versions, `0.11.4` introduced `ImplicitModificationWarning` when setting `.X` on a view.
breakingStarting with `anndata 0.11.0`, support for Python 3.9 has been dropped. If you are using an older Python version, you will need to upgrade your Python environment to 3.10 or higher to use `anndata 0.11.0` and later.fixUpgrade your Python environment to version 3.10 or newer.
affects: >=0.11.0 (specifically from 0.11.0rc3)
breakingThe top-level `anndata.read_*` functions (e.g., `anndata.read_h5ad`) have been moved to `anndata.io` module. Direct imports like `from anndata import read_h5ad` will still work but it's recommended to use the new `anndata.io` module for all read/write operations.fixUpdate import statements from `import anndata as ad; ad.read_h5ad(...)` to `import anndata.io as aio; aio.read_h5ad(...)` or `from anndata.io import read_h5ad`.
affects: >=0.11.0 (specifically from 0.11.0rc2)
deprecatedThe `anndata.__version__` attribute is deprecated. For programmatic version checking, use `importlib.metadata.version('anndata')` instead.fixReplace `anndata.__version__` with `importlib.metadata.version('anndata')`. affects: >=0.12.3
gotchaUsing `anndata.concat()` with `join='outer'` on sparse datasets can significantly increase file size and memory consumption due to the explicit filling of missing variables with zeros. This can quickly lead to out-of-memory errors for large datasets.fixCarefully consider the `join` strategy. If memory is an issue, consider alternative strategies for combining data or ensure you have sufficient resources.
affects: All versions
gotchaWriting keys with forward slashes in `.h5ad` files (`adata.uns['my/nested/key']`) was re-allowed in `0.12.3` but will be disallowed in future versions. This can lead to corrupted file structures or errors in subsequent reads.fixAvoid using forward slashes in keys for `.obs`, `.var`, `.uns`, etc. Use `anndata.settings.disallow_forward_slash_in_h5ad = True` to proactively enforce the future behavior and identify problematic keys.
affects: Future breaking (warned in >=0.12.3)
Upgrade
Version history
0.13.3.post0latest on PyPI · released Aug 27, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.11 or higher.
numpyrequiredFundamental array operations.
scipyrequiredSparse matrix and scientific computing support.
pandasrequiredDataFrame for annotations (`.obs`, `.var`).
h5pyrequiredRequired for HDF5-backed storage (.h5ad files).
zarroptionalSupports Zarr-backed storage (optional, but highly recommended for cloud-native workflows).