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