Skip to content

🧬 OmicVerse 安装指南

📚 For English version, please check Installation Guide (English)

📋 前提条件

OmicVerse 可以通过 conda 或 pip 安装，但首先需要安装 PyTorch。

Note

我们建议在 conda 环境中安装 OmicVerse，以避免依赖冲突。使用 pip install -U omicverse 更新现有安装。

我们还建议使用 uv pip 代替常规的 pip。您可以通过运行 pip install uv 来安装 uv。

平台特定要求

安装 WSL 子系统 并在 WSL 中配置 conda。

从版本 1.6.2 开始，OmicVerse 支持原生 Windows。您需要先安装 torch 和 torch_geometric。

安装 Anaconda 或 Miniconda。

使用 miniforge 或 mambaforge。

Apple Silicon Mac 的重要提示： OmicVerse 需要原生版本的 Python。请使用 Homebrew 安装原生 Apple Silicon 版本的 mambaforge：brew install --cask mambaforge。

🚀 安装方法

快速安装

安装 OmicVerse 最简单的方法是使用我们的安装脚本：

# 仅适用于 Linux
curl -sSL omicverse.com/install | bash -s

国内用户加速版本：

# 仅适用于 Linux（国内加速）
curl -sSL https://starlit.oss-cn-beijing.aliyuncs.com/single/install.sh | bash -s

该脚本会自动： - 设置适当的环境 - 为您的系统安装正确的 PyTorch 版本 - 安装所有必需的依赖项 - 为您的硬件优化配置 OmicVerse

Conda/Mamba

  1. 创建并激活新环境: 

    conda create -n omicverse python=3.10
conda activate omicverse

  2. 安装 PyTorch 和 PyTorch Geometric (PyG): 

    # 对于 CUDA 支持（使用 'nvcc --version' 检查您的 CUDA 版本）
conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia

# 或仅使用 CPU 安装
conda install pytorch torchvision torchaudio cpuonly -c pytorch

# 安装 PyTorch Geometric
conda install pyg -c pyg

  3. 安装 OmicVerse: 

    conda install omicverse -c conda-forge

  4. 验证安装: 

    python -c "import omicverse"

pip/PyPI

  1. 安装 uv（推荐的包管理器）: 
    pip install uv
  2. 安装 PyTorch: 
    uv pip install torch torchvision torchaudio
  3. 安装 PyTorch Geometric: 
    uv pip install torch_geometric
  4. 安装 OmicVerse: 
    uv pip install omicverse
  5. 验证安装: 
    python -c "import omicverse"

其他重要选项

开发版本（最新开发构建）

要安装具有最新功能的开发版本：

# 选项 1: 克隆仓库并本地安装
git clone https://github.com/Starlitnightly/omicverse.git
cd omicverse
pip install .

# 选项 2: 直接从 GitHub 安装
pip install git+https://github.com/Starlitnightly/omicverse.git

开发环境设置

对于想要为 OmicVerse 做贡献的开发者：

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

GPU 加速安装（使用 RAPIDS）

为了获得 GPU 加速的最佳性能：

# 1. 创建新的 conda 环境
conda create -n rapids python=3.11

# 2. 使用 conda 安装 RAPIDS
conda install rapids=24.04 -c rapidsai -c conda-forge -c nvidia -y   

# 3. 安装额外的 RAPIDS 组件
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. 安装 rapids-singlecell
pip install rapids-singlecell

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

注意： 我们安装 RAPIDS 版本 24.04，因为某些系统的 glibc<2.28。如果您的系统支持，您可以按照官方 RAPIDS 教程安装最新版本。

Docker 安装

预构建的 Docker 镜像可在 Docker Hub 上获取。

Jupyter Lab 设置

Jupyter Lab

我们推荐使用 Jupyter Lab 进行交互式分析：

pip install jupyter-lab

安装完成后，激活您的 omicverse 环境并在终端中运行 jupyter-lab。将会出现一个 URL，您可以在浏览器中打开它。

jupyter-light jupyter-dark

故障排除

Linux GCC 设置

# Ubuntu
sudo apt update
sudo apt install build-essential

# CentOS
sudo yum group install "Development Tools"

# 验证 GCC
gcc --version

包安装问题

如果 pip 无法安装某些包（例如 scikit-misc），请尝试使用 conda： 

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

Apple Silicon (M1/M2) 问题

对于遇到问题的 Apple Silicon Mac 用户： 

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

Apple Silicon 要求

重要： OmicVerse 在 Apple Silicon Mac 上需要原生版本的 Python。请确保使用 Homebrew 安装原生 Apple Silicon 版本的 mambaforge： 

brew install --cask mambaforge

MacOS Omp_set_nested 段错误

这通常是由于torch的安装和numpy等冲突了:

在 conda-forge 上： - macOS：libopenblas==openmp - Linux：libopenblas==pthreads

# 1) 先卸载 pip 轮子（关键）
pip uninstall -y numpy scipy scikit-learn threadpoolctl torch torchvision torchaudio pytorch-lightning

# 2) 用 conda-forge 安装干净的 LP64 + OpenBLAS(openmp) 数值栈
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

ILP64 NumPy（openblas64_）用 64 位整数作为 BLAS 下标；很多 Python 扩展（特别是 SciPy/稀疏/包装层）假定 LP64。一旦混到 LP64/ILP64 交叉调用，很容易崩。

两个 libomp.dylib 同时加载（来自 torch 和 sklearn 的 pip wheels 的私有 .dylibs）会造成 OpenMP runtime 重复初始化/符号冲突。

pip + conda 混装使得链接目标不一致：conda 走 OpenBLAS(pthreads)，pip 轮子各自携带 OMP/BLAS 或用 Accelerate，彼此不见得 ABI 兼容。