Installation

安装＃#

康达##

安装 rapids-singlecell 最简单的方法是使用 conda 文件夹中提供的 yaml 文件之一。这些 yaml 文件会安装运行示例 notebook 所需的一切，帮助您快速入门。

conda env create -f conda/rsc_rapids_26.02_cuda13.yml
# or
mamba env create -f conda/rsc_rapids_26.02_cuda13.yml

Python 3.13，CUDA 13.0

conda env create -f conda/rsc_rapids_26.02_cuda12.yml
# or
mamba env create -f conda/rsc_rapids_26.02_cuda12.yml

Python 3.13，CUDA 12.9

笔记

RAPIDS 目前不支持 channel_priority: strict ；请改用 channel_priority: flexible 。

警告

main 分支上的 conda 环境文件引用了新的 rapids-singlecell-cu12 / -cu13 wheel 名称，但这些名称目前仅提供预发布版本。在 0.15.0 版本发布之前，请改用 v0.14.1 标签 中的环境文件，或者手动在 pip 命令中添加 --pre 。

PyPI#

笔记

预发布测试： 版本 0.15.0 目前处于预发布阶段。我们诚邀您参与测试并报告任何问题！请使用以下命令安装最新候选版本：

pip install --pre rapids-singlecell-cu13  # or rapids-singlecell-cu12

请在 GitHub Issues 上报告任何问题。

从 0.15.0 版本开始， rapids-singlecell 通过 nanobind 提供预编译的 CUDA 内核。预编译的 wheel 文件适用于 x86_64 和 aarch64 Linux 系统，支持 CUDA 12 和 CUDA 13。

CUDA 版本兼容性##

预编译的 wheel 文件支持以下 CUDA 运行时版本：

CUDA 12 的 wheel 包使用 CUDA 12.2 编译，以匹配 RAPIDS 26.02 支持矩阵 （CUDA 12.2–12.9）。Blackwell GPU（CC 100、120）通过 PTX 即时编译获得支持，该编译基于 wheel 包中包含的 sm_90 PTX 文件。CUDA 13 的 wheel 包包含原生 Blackwell 二进制文件，因此无需即时编译。

预组装轮组（推荐）##

安装与您的 CUDA 版本相匹配的轮子：

pip install rapids-singlecell-cu13

pip install rapids-singlecell-cu12

此操作会安装预编译的 CUDA 内核，但 不会安装 RAPIDS 协议栈（cupy、cuml、cudf 等）。对于已经在环境中安装了 RAPIDS 的 conda/mamba 用户 ，这是推荐的方法。

预构建的 wheel 文件包含 RAPIDS 依赖项##

要通过 pip 安装 RAPIDS 堆栈，请使用 rapids extra。这需要使用 --extra-index-url 标志来指定 NVIDIA PyPI 索引：

pip install 'rapids-singlecell-cu13[rapids]' --extra-index-url=https://pypi.nvidia.com

pip install 'rapids-singlecell-cu12[rapids]' --extra-index-url=https://pypi.nvidia.com

源代码分发（自编译）##

PyPI 上的 rapids-singlecell 软件包包含源代码分发包。从源代码构建需要 CUDA 工具包和 C++ 编译器：

pip install rapids-singlecell

安装过程中，系统会针对您的本地 GPU 架构编译 CUDA 内核。您可以使用 rapids-cu12 或 rapids-cu13 扩展包选择 RAPIDS 依赖项：

pip install 'rapids-singlecell[rapids-cu12]' --extra-index-url=https://pypi.nvidia.com

笔记

从源代码构建需要您的环境中具备 CUDA 工具包 (nvcc) 和 CMake >= 3.24。

从 GitHub 安装##

要直接从 GitHub 安装最新开发版本：

pip install "rapids-singlecell @ git+https://github.com/scverse/rapids_singlecell.git"

或者从特定分支或标签来看：

pip install "rapids-singlecell @ git+https://github.com/scverse/rapids_singlecell.git@main"

此操作会在安装过程中编译 CUDA 内核。默认情况下，内核仅针对本地 GPU 架构（ native ）进行编译。要针对不同或多个架构进行编译，请传递配置设置以覆盖 CUDA 架构：

# Compile for a specific architecture (e.g., Ampere)
pip install -C cmake.define.CMAKE_CUDA_ARCHITECTURES="80-real" "rapids-singlecell @ git+https://github.com/scverse/rapids_singlecell.git"

# Compile for multiple architectures
pip install -C cmake.define.CMAKE_CUDA_ARCHITECTURES="80-real;86-real;89-real;90-real" "rapids-singlecell @ git+https://github.com/scverse/rapids_singlecell.git"

常用架构代码：

提示

如果只需要在本地 GPU 上运行，请使用 native （默认）以获得最快的编译速度。构建可移植二进制文件时（例如，用于具有混合 GPU 类型的共享集群），请使用多种架构。 -real 后缀仅生成设备代码（不回退到 PTX），从而减小二进制文件的大小。

Docker#

我们还提供 rapids-singlecell 的 Docker 容器。这些容器包含所有必要的依赖项，让您更容易上手 rapids-singlecell 。

要使用 Docker 容器，首先请确保您的系统已安装 Docker，并且 Docker 支持 NVIDIA 容器工具包 。然后，拉取与您的 CUDA 版本匹配的 Docker 镜像：

docker pull ghcr.io/scverse/rapids-singlecell-cu13:latest

docker pull ghcr.io/scverse/rapids-singlecell-cu12:latest

要运行 Docker 容器，请使用以下命令：

docker run --rm --gpus all ghcr.io/scverse/rapids-singlecell-cu13:latest

docker run --rm --gpus all ghcr.io/scverse/rapids-singlecell-cu12:latest

Docker 容器也可以在 HPC 系统上与 Apptainer（或 Singularity）配合使用。

首先拉取容器并将其包装在 .sif 文件中：

apptainer pull rsc.sif docker://ghcr.io/scverse/rapids-singlecell-cu13:latest

apptainer pull rsc.sif docker://ghcr.io/scverse/rapids-singlecell-cu12:latest

然后运行以下命令来执行容器：

apptainer run --nv rsc.sif

系统要求##

大多数计算都在 GPU 上运行。有关硬件指导、管理内存和已知限制，请参阅内存管理页面：

• 内存管理