Source: https://docs.nygen.io/CyteArc/installation/ Revision: fccee7b6e0c167e47ce605c8d292fba5b567ebfe Structured page: https://docs.nygen.io/CyteArc/installation.json Installation CyteArc requires Python 3.13 or newer (requires-python >=3.13). Compiler requirement Note CyteArc depends on hnswlib for KNN graph construction, and hnswlib is published only as a source distribution, so pip and uv compile it during installation. That step needs a C++ compiler: build-essential on Debian and Ubuntu, the Xcode Command Line Tools (xcode-select --install) on macOS. On Windows, install Visual C++ Build Tools with the “Desktop development with C++” workload. 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: Note New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" ` -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force Restart Windows after changing the registry so existing processes do not retain the old value. See the Microsoft long-path documentation . 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 .