Squidpy adds the spatial axis to the scanpy and anndata stack

The spatial layer of the scverse stack

Squidpy is the scverse toolkit for scalable analysis and visualization of spatial molecular data. The one line description is accurate and the rest of the README is about how it earns it.

The key architectural fact is that Squidpy builds on scanpy and anndata. The AnnData object is the data model that the whole scverse ecosystem uses, and scanpy is the analysis layer on top of it. Squidpy does not replace either. It adds the spatial dimension, providing streamlined APIs for feature extraction, spatial statistics, and interactive exploration of tissue sections together with microscopy images.

That design has a practical consequence. A workflow that already loads a Visium or Xenium dataset into anndata and runs scanpy's standard processing can add spatial neighbourhood analysis without restructuring anything, and the objects stay compatible with the rest of the scverse tools. For a field where the analysis code is often written once and then adapted across datasets and assays, that continuity is worth a lot.

The audience is the computational biology side of spatial omics: people who have a tissue section with molecular measurements on it and want to know which cell types sit next to which, whether a gene is spatially clustered, and what the tissue looks like next to the numbers.

Squidpy is part of the scverse project, is fiscally sponsored by NumFOCUS, and is published under the BSD-3-Clause licence.

Four families of capability, and what each one does

The key capabilities list is short enough to be a real specification of the library.

The first is building and analysing spatial neighbour graphs directly from Visium, Slide-seq, Xenium and other spatial omics assays. This is the foundation everything else sits on: a neighbour graph is the object that says which spots or cells are spatial neighbours, and the rest of the library is statistics over that graph.

The second is spatial statistics for cell types and genes, including neighbourhood enrichment, co-occurrence and Moran's I. Neighbourhood enrichment asks whether two cell types are found next to each other more often than chance would predict, co-occurrence measures the same thing as a count, and Moran's I is the spatial autocorrelation statistic that tells you whether a gene's expression is clustered or dispersed in space. Having all three in one library with a shared graph model is the convenience that matters.

The third is efficiently storing, featurizing and visualizing high-resolution tissue microscopy images via scikit-image. Tissue data usually arrives with an image of the section next to the expression matrix, and the image has to be stored in the same object, sliced into tiles, and reduced to features that can be correlated with the molecular data. Featurization is the step that makes an image comparable to a gene.

The fourth is exploring annotated datasets interactively with napari-spatialdata, which is where the viewer has moved, and the README says why.

Installing on a modern Python, and the Windows caveat

The installation section is brief, and the briefness is the message: this is a normal Python package.

The recommendation is to run Squidpy on a recent Linux or macOS system with Python 3.12 or newer, and it also works on Windows via WSL. That last clause is the constraint to notice. A Windows user on native Windows is not the supported path; the supported path is a Linux environment, which means a virtual machine, a container or a cloud instance if you want the full feature set.

From PyPI:

pip install squidpy

Or from conda-forge:

conda install -c conda-forge squidpy

The manifest sets requires-python to 3.12 or newer, and the classifiers list Python 3.12, 3.13 and 3.14. The build system is hatchling with hatch-vcs, which means the version is taken from git tags rather than written into the file, and the distribution status is marked as Production/Stable.

Two other project-level facts show up in the repository listing. There is a .pre-commit-config.yaml and a pre-commit badge, so the formatting and linting are enforced before a commit rather than in review, and there is a biome.jsonc, which is a JavaScript toolchain configuration sitting in a Python repository. The .cruft.json file suggests the template that created the repository is tracked, so updates to that template can be applied later, and the .gitmodules file points to submodule content that is pulled in separately.

The napari plugin was replaced, and that is a migration to plan for

The interactive visualization section is short but it is a deprecation notice, and deprecations are the part of a changelog that costs people time.

For interactive visualization with napari, the README asks you to use napari-spatialdata. The original napari plugin from Squidpy has been deprecated and replaced by napari-spatialdata, which the README says offers improved functionality and support for the SpatialData ecosystem.

Two things follow. First, if you have code that opens a Squidpy napari plugin, that code needs to change, and the replacement is a different package with a different API rather than a new version of the same one. Second, the reason for the change is the SpatialData ecosystem, which is the direction the scverse spatial tools are moving in.

For a group maintaining analysis code across several datasets, this is worth pinning down now. A viewer swap touches the interactive parts of a pipeline, and the interactive parts are usually the parts people built custom views into.

The rest of the ecosystem context is in the scverse project itself, with the website, the governance page and the NumFOCUS sponsorship all linked from the README, plus a request for tax-deductible donations to pay for developer time, professional services, travel and workshops.

The dependency list tells you what the library really does

The pyproject dependencies are more informative about Squidpy than the marketing sentence, because two of them come with comments explaining why they are there.

The first is dask with the array and distributed extras, and the comment says distributed is the only scheduler that forks for GIL-bound featurization. That is the whole explanation of why the library is a distributed computing library as much as a statistics library: featurizing a high-resolution tissue image is CPU-bound Python work, and in a single process it would block everything else in your notebook. The related packages follow from that, with dask-image for the image part and fsspec for the file layer.

The second comment is on legacy-api-wrap, which the manifest says keeps keyword-only args accepting old positional calls, with an issue reference. That is a deliberate compatibility shim: a function that has been converted to keyword-only arguments still accepts the old call style, so a user's existing scripts do not break on a routine API cleanup.

The rest of the list describes the domain. anndata is the data model, matplotlib and matplotlib-scalebar handle the drawing, networkx supplies the graph algorithms that the neighbour and statistics code builds on, aiohttp and centrosome handle the remote and image work, and imagecodecs is pinned to a range below 2026, which is a sign of a dependency that has had to be held back.

The build requires hatchling and hatch-vcs, and the version is dynamic so that it can be set by git tags. The project also carries codecov configuration, an .editorconfig, and a .readthedocs.yaml for the documentation build.

Where Squidpy is the wrong tool

Three cases, one of which is about scope rather than quality.

The first is ordinary single-cell data. If your measurements have no spatial coordinates, there is no neighbour graph to build, no spatial autocorrelation to compute, and Squidpy adds a dependency tree and a Python floor for nothing. Scanpy is the tool for that work, and Squidpy is explicitly a layer on top of scanpy rather than a replacement.

The second is the platform. Python 3.12 or newer is required, and the recommended systems are recent Linux and macOS with Windows supported only via WSL. A lab that runs a fixed, managed Windows desktop image is looking at a virtual machine or a cluster node, and that is a decision to make before you install, not after.

The third is the memory and compute profile of image-heavy work. Featurizing a high-resolution tissue image is the expensive part of the pipeline, and the answer in the dependency list is to fork it across a distributed scheduler. A laptop with a few gigabytes of memory and no cluster is not the environment this was designed for, and a scan with a large image component will be slow there.

One more boundary is worth naming. The statistics are spatial statistics, and they assume a graph that means what the assay means by adjacency. Visium, Slide-seq and Xenium do not define the same geometry, and the loader for each assay encodes that decision. A neighbourhood enrichment result is only as meaningful as the neighbour graph underneath it.

Governance, citation and the release cadence

Squidpy is part of the scverse project and is fiscally sponsored by NumFOCUS, with the README asking for tax-deductible donations to cover developer time, professional services, travel and workshops. The licence is BSD-3-Clause, which is permissive and requires only that the notice is kept, and the repository carries a LICENSE file.

The README asks you to cite the original publication if you use Squidpy in your research, and gives the full BibTeX entry for Palla and colleagues, Squidpy: a scalable framework for spatial omics analysis, published in Nature Methods in 2022, volume 19, number 2, pages 171 to 178.

The release history shows a project in steady maintenance rather than rapid churn. The recent releases are v1.8.3 on 2026-06-29, v1.8.2 on 2026-06-19 and v1.8.1 on 2026-02-09, and the last push was on 2026-10-19 with the repository not archived. Minor releases every few weeks is the pattern of a library whose users depend on a stable API and whose changes are mostly new assay support and fixes.

That is a good position to adopt a research library from. The version line is above 1.0, so the API is expected to be stable, the classifiers mark it as Production/Stable, and the documentation is published on Read the Docs with installation instructions, tutorials, how-to guides and reference pages. The contributing guide covers setting up the environment, running the tests and submitting pull requests, and the repository has separate build and test workflows with a codecov badge, so the code that ships is the code that was measured.

If you adopt it, pin the version you tested, and read the release notes for the assay loaders you rely on.

Editorial conclusion

Squidpy suits a computational biologist working with spatial transcriptomics or imaging mass cytometry data who already uses scanpy and anndata and wants the spatial neighbourhood machinery, the spatial statistics and the image side of the analysis in one place with a consistent API. It is the wrong choice for non-spatial single-cell work, where scanpy is the tool, and for a workflow that cannot move to Python 3.12 or run on Linux or macOS, since Windows is supported only through WSL. Verify first that the assay you work with has a working loader in the current release, check the napari-spatialdata migration if you use the interactive viewer, and read the dependency list before you commit, because the image and dask stack is heavier than a pure expression matrix workflow.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. scverse/squidpy on GitHub