Local development setup#
This page walks you through setting up a development environment for cellucid-python (Python package + CLI + docs).
It is intentionally detailed so that:
first-time contributors don’t get stuck on environment issues,
computational users can reproduce bugs reliably,
and maintainers have a repeatable workflow.
Prerequisites#
Required:
Python
>=3.10Git
Recommended:
a fresh virtual environment (
venv,conda,uv, etc.)
Optional (only if you work on notebook embedding):
JupyterLab / VSCode notebooks / classic notebook
Step 0 — Choose which repo(s) you’re working on#
Cellucid is split across repositories:
Python package (this page):
cellucid-python/Web app (UI/rendering):
cellucid/(see Developer Documentation (Web App Architecture))
If you are changing the export format or hooks protocol, you will likely touch both repos.
Step 1 — Create an isolated environment#
Using venv:
python -m venv .venv
source .venv/bin/activate # Windows: .venv\\Scripts\\activate
python -m pip install --upgrade pip
If you use conda, the key requirement is “Python 3.10+ and a clean environment”; the rest is the same.
Step 2 — Install in editable mode (dev + docs extras)#
From the cellucid-python/ folder:
python -m pip install -e ".[dev,docs]"
What this does:
installs runtime dependencies,
installs developer tooling (
pytest,ruff,mypy,pre-commit),installs documentation tooling (Sphinx + MyST).
Step 3 — Quick sanity checks#
3.1 Import + version#
python -c "import cellucid; print(cellucid.__version__)"
3.2 CLI help#
cellucid --help
cellucid serve --help
If the CLI is slow or crashes, jump to: CLI architecture and commands.
3.3 Run tests#
pytest
If tests are missing for what you changed, see: Testing and CI.
Step 4 — Build the docs locally#
From the cellucid-python/ folder:
make -C docs html
Then open:
cellucid-python/docs/_build/html/index.html
Common variants:
make -C docs clean
make -C docs linkcheck
Doc-writing conventions live here: Docs development and style guide
Step 5 — Run a viewer locally (for manual testing)#
You can test with either:
Option A: exported folder (fastest + most representative)#
Export your dataset:
from cellucid import prepare
# ... call prepare(...) to write an export folder ...
Serve it:
cellucid serve ./my_export
Option B: AnnData server (convenient during iteration)#
cellucid serve ./data.h5ad
Both modes should open the viewer in a browser automatically (unless --no-browser).
Step 6 — Notebook embedding (optional, but common)#
Notebook embedding is the “hardest environment” because of proxies, mixed-content, and remote kernels.
Minimal test:
from cellucid import show_anndata
viewer = show_anndata("path/to/data.h5ad")
viewer # show the iframe output
If the iframe is blank or hooks don’t work:
run
viewer.debug_connection(),follow Debugging playbook,
see notebook architecture details in Jupyter embedding architecture.
Offline / airgapped development notes#
The Python servers run in hosted-asset proxy mode by default:
they fetch the web UI from
https://www.cellucid.com,cache it locally,
and serve it from the same origin as the dataset server (avoids mixed-content).
If you are offline:
run once while online to populate the cache,
then reuse that cache.
You can control where the cache lives:
CELLUCID_WEB_PROXY_CACHE_DIR(see Configuration, environment variables, and logging)
Troubleshooting#
Symptom: “pip install -e ".[dev,docs]" fails”#
Likely causes:
conflicting packages already installed in the environment,
old pip/setuptools,
corporate proxy restrictions.
Fix checklist:
ensure you activated the correct environment,
upgrade pip:
python -m pip install --upgrade pip,try a fresh environment.
Symptom: “Docs build fails with missing dependencies”#
Confirm you installed the docs extras:
python -m pip show sphinx myst-nb
Then rebuild:
make -C docs clean html