Installation¶

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

For exact MCP client syntax, see Configuration Guide.
For your first workflow after setup, see Quick Start.
For installation failures, see Troubleshooting.

Requirements¶

Python 3.11-3.13 (3.12 recommended)
8GB+ RAM (16GB+ for large datasets)
macOS, Linux, or Windows

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 all major methods
uv pip install chatspatial[full]

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
Full	`uv pip install chatspatial[full]`	You want the broadest method coverage
Standard	`uv pip install chatspatial`	You only need core functionality

Alternative: pip

pip install --upgrade pip
pip install chatspatial[full]

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

Step 3: Register ChatSpatial in Your MCP Client¶

Activate your environment.
Get the absolute Python path:

which python

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

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¶

For RCTD, SPOTlight, CARD, CellChat, SPARK-X, scType, Numbat, and SCTransform:

# 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¶

Configuration Guide — exact client setup
Quick Start — first successful analysis
Troubleshooting — fix install or runtime issues