Installation

CyteArc requires Python 3.13 or newer (requires-python >=3.13).

Compiler requirement¶

On Debian or Ubuntu, install the compiler before installing CyteArc:

sudo apt install build-essential

When the alternative pip path below uses the distribution’s system Python, install its development headers and virtual-environment support before running python -m venv:

sudo apt install python3-dev python3-venv

The unversioned packages match the distribution’s default python3. For a separately installed system interpreter, install the matching packages, such as python3.13-dev and python3.13-venv. A uv-managed Python already includes its development headers and virtual-environment support.

Recommended: uv environment¶

Run these commands in the directory where you will work. uv creates an isolated .venv so CyteArc does not modify the system Python:

uv venv --python 3.13

Activate the environment on macOS or Linux:

source .venv/bin/activate

Or activate it in Windows PowerShell:

.venv\Scripts\Activate.ps1

Install CyteArc into the activated environment:

uv pip install --prerelease allow "cytearc[extra]"

CyteArc 1.0.0rc1 is in preparation. The installation commands apply once the release candidate is published. Use --prerelease allow to let uv select a release candidate. The extra optional dependency group adds plotting (matplotlib, seaborn), AnnData support, widgets, and other helpers used by the tutorials.

Verify the install with the Python interpreter from the same environment. import cytearc defers most modules until their first use, so the check also imports DataStore:

python -c "from cytearc import DataStore; import cytearc; print(cytearc.__version__)"

Alternative: pip environment¶

If uv is unavailable, first confirm that python is version 3.13 or newer, then create and activate a standard virtual environment:

python -m venv .venv

Use the macOS, Linux, or Windows activation command above, then install and verify CyteArc. --pre is pip’s equivalent of uv’s --prerelease allow:

python -m pip install --pre "cytearc[extra]"
python -c "from cytearc import DataStore; import cytearc; print(cytearc.__version__)"

Alternative: conda environment¶

This path installs a prebuilt hnswlib from conda-forge and is recommended on Windows when Visual C++ Build Tools are unavailable:

conda create --name cytearc_env --channel conda-forge python=3.13 pip "hnswlib>=0.8"
conda activate cytearc_env
python -m pip install --pre "cytearc[extra]"
python -c "from cytearc import DataStore; import cytearc; print(cytearc.__version__)"

The conda package satisfies CyteArc’s hnswlib>=0.8 requirement, so pip does not compile it.

CyteBase SDK¶

To search CyteBase and connect directly to its cloud-hosted CyteArc DataStores, install the cytebase extra in your local or cloud Python environment:

uv pip install --prerelease allow "cytearc[cytebase,extra]"

This adds DuckDB for catalog queries and the SDK’s plotting dependencies. cytebase.Catalog() defaults to the current public, read-only release, Nygen/cytebase-2610, without requiring credentials. Pass version="2610.1" to open another release, or set CYTEBASE_BUCKET or pass bucket= to use another catalog, then follow Explore CyteBase. See CyteBase API reference for the full SDK reference.

Optional t-SNE¶

embeddings.tsne and the pipeline’s tsne stage compute t-SNE with the sgtsnepi package, which CyteArc does not install by default. Add it with the tsne extra, in the same environment as CyteArc:

uv pip install --prerelease allow "cytearc[extra,tsne]"

sgtsnepi publishes wheels only for Linux x86_64 and for macOS 26 or newer on Apple silicon (arm64). On other platforms the installer compiles it from source, which needs a C++ compiler and FFTW, and sgtsnepi does not support Windows. It runs on one thread, and it is licensed under the GPLv3, while CyteArc is BSD-3-Clause and does not depend on it unless you install the extra. Without sgtsnepi, computing a new t-SNE embedding raises an ImportError that names the tsne extra. Reusing a t-SNE embedding that a store already holds, and plotting or exporting it, does not need sgtsnepi. A pipeline run that enables t-SNE without sgtsnepi therefore still runs, and it logs a warning that names the extra before its first stage.

JupyterLab¶

Install and launch JupyterLab from the same activated environment as CyteArc. For the uv environment:

uv pip install jupyterlab
jupyter lab

For the pip environment:

python -m pip install jupyterlab
jupyter lab

For the conda environment, install JupyterLab and register an explicit kernel:

conda install --channel conda-forge jupyterlab ipykernel
python -m ipykernel install --user --name cytearc_env --display-name "Python (cytearc_env)"
jupyter lab

Select Python (cytearc_env) when opening a notebook from another Jupyter environment.

Windows paths¶

CyteArc’s nested Zarr stores can exceed the default Windows path limit. Enable long paths in PowerShell run as Administrator:

Upgrade CyteArc¶

Activate the environment that contains CyteArc, then use the same installer:

uv pip install --upgrade --prerelease allow "cytearc[extra]"

Or, for pip and conda environments:

python -m pip install --upgrade --pre "cytearc[extra]"

Install from source¶

Clone the repository and let uv create an editable project environment:

git clone https://github.com/NygenAnalytics/CyteArc.git
cd CyteArc
uv sync --extra extra
uv run python -c "from cytearc import DataStore; import cytearc; print(cytearc.__version__)"

See Contributing before making package or documentation changes.

Troubleshooting¶

• No virtual environment found: activate .venv, or pass it explicitly with uv pip install --python .venv --prerelease allow "cytearc[extra]".

• hnswlib fails to build: install the compiler and, for a system Python, matching development headers described above. On Windows without Build Tools, use the conda path.

• embeddings.tsne raises ImportError naming the tsne extra: install the extra as described in Optional t-SNE, or use UMAP.

• CyteArc imports in a terminal but not a notebook: compare the terminal path from python -c "import sys; print(sys.executable)" with the notebook kernel, then launch Jupyter from the CyteArc environment or select its registered kernel.

Next steps¶

After the import check succeeds, continue with the Quick start.