Skip to content

🧬 OmicVerse Installation Guide

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

📋 Prerequisites

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

Note

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

Platform-Specific Requirements

  • Windows (WSL): Install the WSL subsystem and configure conda within WSL
  • Windows (Native): From version 1.6.2, OmicVerse supports native Windows (requires torch and torch_geometric)
  • Linux: Install Anaconda or Miniconda
  • macOS: Use miniforge or mambaforge

pip Prerequisites

  • If using conda/mamba: Run conda install -c anaconda pip and skip this section
  • Otherwise: Install Python (preferably using pyenv with pyenv-virtualenv)

Apple Silicon Note

OmicVerse requires a native version of Python on Apple Silicon Macs. Install using a native Apple Silicon version of mambaforge (available via Homebrew with brew install --cask mambaforge).

🚀 Installation Methods

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

#Only for Linux
curl -sSL https://raw.githubusercontent.com/Starlitnightly/omicverse/refs/heads/master/install.sh | 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

📦 Using Conda

  1. Create and activate environment: 

    conda create -n omicverse python=3.10
conda activate omicverse

  2. Install PyTorch and PyG: 

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

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

# Install PyG
conda install pyg -c pyg

  3. Install OmicVerse: 

    conda install omicverse -c conda-forge

  4. Verify installation: 

    python -c "import omicverse"

📦 Using pip

  1. Install PyTorch: 
    # For CUDA 11.8
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# OR for CPU only
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
  2. Install PyG: 
    # Install base PyG
pip install torch_geometric

# Check versions
python -c "import torch; print(torch.__version__)"
python -c "import torch; print(torch.version.cuda)"
  3. Install PyG Extensions:

    ⚠️ Not Recommended Method

    # For Windows with CPU
pip install torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-${TORCH}+cpu.html

# For systems with CUDA
pip install torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-${TORCH}+${CUDA}.html

    Replace ${TORCH} and ${CUDA} with your version numbers:

    PyTorch Version TORCH Value CUDA Options
    PyTorch 2.7 2.7.0 cpu/cu122/cu124
    PyTorch 2.6 2.6.0 cpu/cu122/cu124
    PyTorch 2.5 2.5.0 cpu/cu118/cu121/cu122
    PyTorch 2.4 2.4.0 cpu/cu118/cu121
    PyTorch 2.3 2.3.0 cpu/cu118/cu121
    PyTorch 2.2 2.2.0 cpu/cu118/cu121
    PyTorch 2.1 2.1.0 cpu/cu118/cu121
    PyTorch 2.0 2.0.0 cpu/cu117/cu118
    PyTorch 1.13 1.13.0 cpu/cu116/cu117

    Example commands:

    # For PyTorch 2.7 with CUDA 12.4
pip install torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.7.0+cu124.html

# For PyTorch 2.3 with CUDA 12.1
pip install torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.3.0+cu121.html

# For PyTorch 2.2 with CUDA 11.8
pip install torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.2.0+cu118.html

    ✅ Recommended Method

    conda install -c conda-forge pytorch_scatter pytorch_sparse pytorch_cluster pytorch_spline_conv
  4. Linux GCC Setup (Linux only): 
    # Ubuntu
sudo apt update
sudo apt install build-essential

# CentOS
sudo yum group install "Development Tools"

# Verify GCC
gcc --version
  5. Install OmicVerse: 
    # Basic installation
pip install -U omicverse

# Install Numba for performance optimization
pip install -U numba

# OR full installation with spatial RNA-seq support
pip install omicverse[full]
  6. Verify installation: 
    python -c "import omicverse"

🔧 Advanced Options

Nightly Version

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

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

GPU-Accelerated Installation

# Using conda/mamba
conda env create -f conda/omicverse_gpu.yml
# OR
mamba env create -f conda/omicverse_gpu.yml

Docker

Docker images are available on Docker Hub.

📊 Jupyter Lab Setup

We recommend Jupyter Lab for interactive analysis:

pip install jupyter-lab

After installation, run jupyter-lab in your terminal (from the omicverse environment). A URL will appear that you can open in your browser.

jupyter-light jupyter-dark

🛠️ Development Setup

For development:

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

❓ Troubleshooting

  • Package installation issues: If pip cannot install certain packages (e.g., scikit-misc), try conda: 

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

  • Apple Silicon (M1/M2) issues: 

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