Skip to content

🧬 OmicVerse Installation Guide

📚 For the Chinese version, please check 安装指南 (中文版)

📋 Prerequisites

OmicVerse can be installed via conda or pip, but you must install PyTorch first.

Note

We recommend installing OmicVerse within a conda environment to avoid dependency conflicts. Use pip install -U omicverse to update existing installations.

We also recommend using uv pip instead of regular pip. You can install uv by running pip install uv.

Platform-Specific Requirements

Install the WSL subsystem and configure conda within WSL.

Starting from version 1.6.2, OmicVerse supports native Windows. You'll need to install torch and torch_geometric first.

Install Anaconda or Miniconda.

Use miniforge or mambaforge.

Important for Apple Silicon Macs: OmicVerse requires a native version of Python. Install a native Apple Silicon version of mambaforge using Homebrew: brew install --cask mambaforge.

🚀 Installation Methods

Quick Installation

The easiest way to install OmicVerse is using our installation script:

# Linux only
curl -sSL omicverse.com/install | bash -s

This script will automatically: - Set up the appropriate environment - Install the correct PyTorch version for your system - Install all required dependencies - Configure OmicVerse optimally for your hardware

Conda/Mamba

  1. Create and activate a new environment: 

    conda create -n omicverse python=3.10
conda activate omicverse

  2. Install PyTorch and PyTorch Geometric (PyG): 

    # For CUDA support (check your CUDA version with 'nvcc --version')
conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia

# OR for CPU-only installation
conda install pytorch torchvision torchaudio cpuonly -c pytorch

# Install PyTorch Geometric
conda install pyg -c pyg

  3. Install OmicVerse: 

    conda install omicverse -c conda-forge

  4. Verify the installation: 

    python -c "import omicverse"

pip/Pypi

  1. Install uv (recommended package manager): 
    pip install uv
  2. Install PyTorch (Installing with pip on macOS may encounter some issues.): 
    uv pip install torch torchvision torchaudio
  3. Install PyTorch Geometric: 
    uv pip install torch_geometric
  4. Install OmicVerse: 
    uv pip install omicverse
  5. Verify the installation: 
    python -c "import omicverse"

Other Important Options

Nightly Version (Latest Development Build)

To install the latest development version with newest features:

# Option 1: Clone repository and install locally
git clone https://github.com/Starlitnightly/omicverse.git
cd omicverse
pip install .

# Option 2: Install directly from GitHub
pip install git+https://github.com/Starlitnightly/omicverse.git

Development Setup

For developers who want to contribute to OmicVerse:

pip install -e ".[dev,docs]"

GPU-Accelerated Installation (with RAPIDS)

For maximum performance with GPU acceleration:

# 1. Create a new conda environment
conda create -n rapids python=3.11

# 2. Install RAPIDS using conda
conda install rapids=24.04 -c rapidsai -c conda-forge -c nvidia -y   

# 3. Install additional RAPIDS components
conda install cudf=24.04 cuml=24.04 cugraph=24.04 cuxfilter=24.04 cucim=24.04 pylibraft=24.04 raft-dask=24.04 cuvs=24.04 -c rapidsai -c conda-forge -c nvidia -y   

# 4. Install rapids-singlecell
pip install rapids-singlecell

# 5. Install OmicVerse
curl -sSL https://raw.githubusercontent.com/Starlitnightly/omicverse/refs/heads/master/install.sh | bash -s

Note: We install RAPIDS version 24.04 because some systems have glibc<2.28. You can follow the official RAPIDS tutorial to install the latest version if your system supports it.

Docker Installation

Pre-built Docker images are available on Docker Hub.

Jupyter Lab Setup

Jupyter Lab

We recommend using Jupyter Lab for interactive analysis:

pip install jupyter-lab

After installation, activate your omicverse environment and run jupyter-lab in your terminal. A URL will appear that you can open in your browser.

jupyter-light jupyter-dark

Troubleshooting

Linux GCC Setup

# Ubuntu
sudo apt update
sudo apt install build-essential

# CentOS
sudo yum group install "Development Tools"

# Verify GCC
gcc --version

Package Installation Issues

If pip fails to install certain packages (e.g., scikit-misc), try using conda instead: 

conda install scikit-misc -c conda-forge -c bioconda

Apple Silicon (M1/M2) Issues

For Apple Silicon Mac users experiencing issues: 

conda install s_gd2 -c conda-forge
pip install -U omicverse
conda install pytorch::pytorch torchvision torchaudio -c pytorch

Apple Silicon Requirements

Important: OmicVerse requires a native version of Python on Apple Silicon Macs. Make sure to install a native Apple Silicon version of mambaforge using Homebrew: 

brew install --cask mambaforge

MacOS Omp_set_nested routine deprecated

For Apple Silicon Mac users experiencing issues: 

# 1| First uninstall pip wheels (important)
pip uninstall -y numpy scipy scikit-learn threadpoolctl torch torchvision torchaudio pytorch-lightning

# 2| Install clean LP64 + OpenBLAS(openmp) numerical stack from conda-forge
mamba install -c conda-forge \
  "numpy>=1.26,<2" "scipy>=1.11,<2" anndata "scanpy>=1.10" pandas \
  scikit-learn numexpr threadpoolctl \
  "libblas=*=*openblas" "libopenblas=*=*openmp" libomp

# 3| Install pytorch with conda
mamba install -c pytorch -c conda-forge pytorch torchvision torchaudio