Installation

This page is the docs-site version of the installation guide. It is the canonical installation page for the documentation site.

Requirements

  • Python 3.11-3.13 (3.12 recommended)

  • 8GB+ RAM (16GB+ for large datasets)

  • macOS, Linux, or Windows

Docker Installation

If local installation fails or you want the most reproducible setup, use the published Docker image:

# Pull and verify the image
docker pull ghcr.io/cafferychen777/chatspatial:latest
docker run --rm ghcr.io/cafferychen777/chatspatial:latest --version
docker run --rm ghcr.io/cafferychen777/chatspatial:latest server --help

Use this command shape in MCP clients that support Docker-backed stdio servers:

docker run --rm -i \
  -v /absolute/path/to/your/data:/data:ro \
  -v /absolute/path/to/outputs:/outputs \
  ghcr.io/cafferychen777/chatspatial:latest server --transport stdio

Mounted data are available under /data, and generated outputs are written under /outputs by default. In prompts, use container paths such as /data/sample.h5ad, not the original host path.

See Docker / GHCR for MCP client examples, SSE mode, volume details, and local source builds.

Step 1: Create an Environment

# venv
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate   # Windows

# or conda
conda create -n chatspatial python=3.12
conda activate chatspatial

Step 2: Install ChatSpatial

Recommended: use uv for dependency resolution

# Install uv if needed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the MCP server and core analysis stack
uv pip install chatspatial

Why uv? ChatSpatial depends on a large scientific Python stack. Standard pip can fail on deep dependency resolution; uv is more reliable for this environment.

Install options

Option

Command

Use when

Standard

uv pip install chatspatial

You want the MCP server, data loading, preprocessing, embeddings, visualization, and core analysis

Method extras

uv pip install 'chatspatial[cell-communication,velocity]'

You need specific advanced method families

Full

uv pip install 'chatspatial[full]'

You want the broadest method coverage on a workstation and accept a large install. Requires R ≥ 4.4 on PATH (see below)
Alternative: pip 
pip install --upgrade pip
pip install chatspatial

If you hit resolution-too-deep, switch to uv.

Optional method families

Install only the method families you plan to use:

uv pip install 'chatspatial[cell-communication]'  # LIANA+, CellPhoneDB, FastCCC
uv pip install 'chatspatial[velocity]'            # scVelo
uv pip install 'chatspatial[deep-learning]'       # scVI, scANVI, VeloVI, DestVI backend
uv pip install 'chatspatial[integration]'         # Harmony, BBKNN, Scanorama
uv pip install 'chatspatial[deconvolution]'       # FlashDeconv, Cell2location
uv pip install 'chatspatial[spatial-stats]'       # PySAL/ESDA extensions

ChatSpatial tools fail with targeted installation guidance if you call a method whose optional dependency is not installed.

Step 3: Register ChatSpatial in Your MCP Client

  1. Activate your environment.

  2. Get the absolute Python path:

which python

  1. Register ChatSpatial using this command shape:

/absolute/path/to/python -m chatspatial server

  1. Restart your client after configuration changes.

For exact client-specific syntax, use the Configuration Guide.

Step 4: Verify the Installation

python -c "import chatspatial; print(f'ChatSpatial {chatspatial.__version__} ready')"
python -m chatspatial server --help

If both commands work, continue to Quick Start.

Platform Notes

Windows

Not available: SingleR, PETSc

Use instead: Tangram, scANVI, CellAssign for annotation; CellRank works without PETSc.

If Python or MCP dependencies fail to resolve

rm -rf venv
python3.12 -m venv venv
source venv/bin/activate
uv pip install chatspatial[full]

Optional Dependencies

R-based methods

The [full] extra includes rpy2, which requires R to be available on your PATH at install time (it compiles against your R installation). On HPC systems where R is provided via modules, run module load R (or equivalent) before installing. If you only need Python-based methods, the standard install (uv pip install chatspatial) does not require R.

Once R is available, install the R packages used by ChatSpatial:

# Install R 4.4+
Rscript install_r_dependencies.R

STAGATE

git clone https://github.com/QIFEIDKN/STAGATE_pyG.git
cd STAGATE_pyG && python setup.py install

Next Steps