🧬 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 (requirestorch
andtorch_geometric
) - Linux: Install Anaconda or Miniconda
- macOS: Use
miniforge
ormambaforge
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¶
🔥 Quick Installation (Recommended)¶
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¶
-
Create and activate environment:
conda create -n omicverse python=3.10 conda activate omicverse
-
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
-
Install OmicVerse:
conda install omicverse -c conda-forge
-
Verify installation:
python -c "import omicverse"
📦 Using pip¶
- 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
- 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)"
- 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
- 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
- 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]
- 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.
🛠️ 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