RAPIDS 安装指南

RAPIDS 有几种安装方法，取决于首选环境和版本。新用户应仔细阅读系统和环境的先决条件。

使用 Release Selector 安装 RAPIDS

安装故障排除

系统要求

操作系统、NVIDIA GPU 驱动程序和 CUDA 版本
系统推荐
云实例 GPU

环境设置

Conda
Docker
pip
SDK Manager
Windows WSL2
- SDK Manager
- Conda
- Docker
- pip
从源代码构建

下一步

安装 RAPIDS

使用下方的选择工具选择您首选的安装方法、软件包和环境来安装 RAPIDS。某些组合可能不可行，并会自动变暗。

发布版本

方法

环境 CUDA

系统 CUDA

镜像 CUDA

Python

RAPIDS 软件包

附加软件包

软件包

镜像位置

镜像类型

命令

复制命令

安装故障排除

Conda 问题

发生 conda create error 错误
要解决此错误，请按照以下步骤之一操作

如果 Conda 安装版本早于 22.11，请更新到最新版本。这将包含 libmamba，一个由 Mamba 提供支持的 Conda 求解器，现在所有 conda 安装都包含它，可以显著加速环境求解。
如果 Conda 安装版本为 22.11 或更高，请运行： conda install -n base conda-libmamba-solver 并运行 conda create --solver=libmamba ...
直接使用 Mamba，即 mamba create ...

发生 __cuda 约束冲突
您可能会看到类似如下的信息

LibMambaUnsatisfiableError: Encountered problems while solving:
 - package cuda-version-12.0-hffde075_0 has constraint __cuda >=12 conflicting with __cuda-11.4-0

这意味着您机器上当前安装的 CUDA 驱动程序（例如 __cuda: 11.4.0）与您尝试安装的 cuda-version (12.0) 不兼容。您必须确保您机器上的 CUDA 驱动程序支持您尝试使用 conda 安装的 CUDA 版本。

如果 conda 错误地识别了 CUDA 驱动程序，您可以通过设置 CONDA_OVERRIDE_CUDA 环境变量来覆盖。

Docker 问题

RAPIDS 23.08 带来了重大的 Docker 更改。
要了解有关这些更改的更多信息，请参阅 RAPIDS 容器 README。下面是一些关键说明

Development 镜像不再发布，RAPIDS 现在使用 Dev Containers 进行开发
- 有关 RAPIDS 使用 Dev Containers 的示例和信息，请参阅 cuDF
所有镜像都基于 Ubuntu
- CUDA 12.5+ 镜像使用 Ubuntu 24.04
- 所有其他镜像使用 Ubuntu 22.04
所有镜像都支持多架构 (x86_64 和 ARM)
base 镜像以 ipython shell 启动
- 要在 ipython shell 内运行 bash 命令，请在命令前加上 !
- 要在不启动 ipython shell 的情况下运行镜像，请在 docker run 命令末尾添加 /bin/bash
有关完整的更改列表，请参阅此 RAPIDS Docker 问题

pip 问题

pip 安装需要使用与系统安装的 CUDA toolkit 相匹配的 wheel。对于 CUDA 11 toolkits，安装 -cu11 wheels，对于 CUDA 12 toolkits 安装 -cu12 wheels。如果您的安装有 CUDA 12 驱动程序但有 CUDA 11 toolkit，请使用 -cu11 wheels。
尚不支持 Infiniband。
这些软件包与 Tensorflow pip 软件包不兼容。请改用 NGC 容器或 conda 软件包。
如果您遇到“Failed to import CuPy”错误，请卸载任何现有版本的 cupy 并安装 cupy-cuda11x。例如

pip uninstall cupy-cuda115; pip install cupy-cuda11x

以下错误消息表示您的环境有问题

ERROR: Could not find a version that satisfies the requirement cudf-cu12 (from versions: 0.0.1, 25.04)
ERROR: No matching distribution found for cudf-cu12

检查下面的建议以获取可能的解决方案

pip 索引已从最初的实验版本迁移！确保使用正确的 --extra-index-url=https://pypi.nvidia.com
确保您使用的 Python 版本是 RAPIDS 支持的版本（将安装选择器中的值与 python --version 报告的 Python 版本进行比较）。
RAPIDS pip 软件包需要一个支持 PEP600 的最新版本 pip。有些用户可能需要更新 pip： pip install -U pip

可能发生 Dask / Jupyter / Tornado 6.2 依赖冲突。如果发生以下错误，请安装 jupyter-client 7.3.4

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behavior is the source of the following dependency conflicts.
jupyter-client 7.4.2 requires tornado>=6.2, but you have tornado 6.1 which is incompatible.

cuSpatial 安装可能出现以下错误

ERROR: GDAL >= 3.2 is required for fiona. Please upgrade GDAL.

要解决此问题，需要更新 GDAL，或者根据安装的操作系统将 fiona 锁定到特定版本。请参阅 cuSpatial README 来解决此错误。

WSL2 问题

请参阅 WSL2 设置的故障排除部分。

系统要求

操作系统 / GPU 驱动程序 / CUDA 版本

所有准备好的系统都需要具备运行 RAPIDS 的能力。以下是所需条件

GPU： NVIDIA Volta™ 或更高版本，计算能力 (compute capability) 7.0+，详情请查阅 CUDA GPUs。

Pascal™ GPU 支持已在 24.02 版本中移除。RAPIDS 24.02 及更高版本需要计算能力 7.0+。

操作系统：

使用 glibc>=2.28（发布于 2018 年 8 月）的 Linux 发行版，包括以下版本
- Arch Linux，最低版本 2018-08-02
- Debian，最低版本 10.0
- Fedora，最低版本 29
- Linux Mint，最低版本 20
- Rocky Linux / Alma Linux / RHEL，最低版本 8
- Ubuntu，最低版本 20.04
使用 WSL2 特定安装的 Windows 11

CUDA 和 NVIDIA 驱动程序： 支持以下版本之一

CUDA 11.2 及驱动程序 470.42.01 或更新版本
CUDA 11.4 及驱动程序 470.42.01 或更新版本
CUDA 11.5 及驱动程序 495.29.05 或更新版本
CUDA 11.8 及驱动程序 520.61.05 或更新版本
CUDA 12.0 及驱动程序 525.60.13 或更新版本 关于用法请参见下方的 CUDA 12 部分
CUDA 12.2 及驱动程序 535.86.10 或更新版本 关于用法请参见下方的 CUDA 12 部分
CUDA 12.5 及驱动程序 555.42.06 或更新版本 关于用法请参见下方的 CUDA 12 部分

注意：RAPIDS 经过以上列出版本的测试并官方支持这些版本。较新的 CUDA 和驱动程序版本也可能与 RAPIDS 兼容。详情请参阅 CUDA 兼容性。

CUDA 支持

Docker 和 Conda

conda 软件包和 Docker 镜像支持在具有 CUDA 12 驱动程序的系统上使用 CUDA 12。
CUDA 11 conda 软件包和 Docker 镜像可以在具有 CUDA 12 驱动程序的系统上使用，因为它们包含自己的 CUDA toolkit。

pip

pip 安装需要使用与系统安装的 CUDA toolkit 相匹配的 wheel。
RAPIDS pip 软件包需要 NVRTC 才能使 Numba 正常工作。对于 Docker 用户，这意味着 RAPIDS wheels 需要 nvidia/cuda 镜像的 devel 版本才能获得完整功能。当前 nvidia/cuda Docker 镜像的 base 和 runtime 版本尚不足够。
对于 CUDA 11 toolkits，安装 -cu11 wheels，对于 CUDA 12 toolkits 安装 -cu12 wheels。如果您的安装有 CUDA 12 驱动程序但有 CUDA 11 toolkit，请使用 -cu11 wheels。

系统推荐

除了系统要求外，获得最佳性能的其他考量包括

SSD 硬盘 (首选 NVMe)
系统内存与总 GPU 内存约 2:1 的比例（尤其对 Dask 有用）
NVLink 连接 2 个或更多 GPU

云实例 GPU

如果您无法访问 GPU 硬件，有几家云服务提供商 (CSP) 支持 RAPIDS。请访问我们的云部署页面，了解如何在 AWS、Azure、GCP 和 IBM Cloud 上部署 RAPIDS。

一些服务还提供带有 GPU 资源的免费且有限的试用

环境设置

对于大多数安装，您需要安装 Conda 或 Docker 环境来运行 RAPIDS。请注意，这些示例是针对在 Ubuntu 上安装而构建的。对于 Rocky Linux 请相应修改。Windows 11 有一个WSL2 特定安装。

Conda

RAPIDS 可以与任何 conda 发行版一起使用。

以下是使用 miniforge 的安装指南。

1. 下载并运行安装脚本。复制以下命令下载并运行 miniforge 安装脚本

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

2. 自定义 Conda 并运行安装。 使用终端窗口完成安装。注意，我们建议启用 conda-init。

3. 启动 Conda。 打开一个新的终端窗口，现在应该显示 Conda 已初始化。

4. 检查 Conda 配置。 安装 RAPIDS 可能需要您使用 channel_priority: flexible。

如果您使用 CUDA 12 或更高版本安装 RAPIDS，则可以使用 strict 或 flexible 频道优先级。

如果您使用 CUDA 11 安装 RAPIDS，则必须设置 channel_priority: flexible。

您可以通过以下命令检查并更改它（如果需要）

conda config --show channel_priority
conda config --set channel_priority flexible

Docker

RAPIDS 需要安装 Docker CE v19.03+ 和 nvidia-container-toolkit。

遗留支持：Docker CE v17-18 和 nvidia-docker2

1. 下载并安装。 复制以下命令下载并安装最新的 Docker CE Edition

curl https://get.docker.com | sh

2. 安装最新的 NVIDIA Docker。 选择适当的支持发行版

curl -s -L https://nvda.org.cn/nvidia-container-runtime/gpgkey | sudo apt-key add - distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvda.org.cn/nvidia-container-runtime/$distribution/nvidia-container-runtime.list | sudo tee /etc/apt/sources.list.d/nvidia-container-runtime.list
sudo apt-get update
sudo apt-get install nvidia-container-runtime

3. 启动 Docker。 在新的终端窗口中运行

sudo service docker stop
sudo service docker start

4a. 测试 NVIDIA Docker。 在终端窗口中运行

docker run --gpus all nvcr.io/nvidia/k8s/cuda-sample:nbody nbody -gpu -benchmark

4b. 遗留 Docker 用户。 Docker CE v18 和 nvidia-docker2 用户需要将 docker run --gpus all 替换为 docker run --runtime=nvidia 以保持兼容性。

JupyterLab。

用于 notebooks Docker 镜像的选择器提供的命令将在您的主机机器上运行 JupyterLab，端口为： 8888。

运行多节点/多 GPU (MNMG) 环境。 要在 MNMG 环境中启动容器

docker run -t -d --gpus all --shm-size=1g --ulimit memlock=-1 --ulimit stack= 67108864 -v $PWD:/ws <container label>

标准的 docker 命令可能就足够了，但附加参数可以确保更高的稳定性。有关 MNMG 用法的更多详细信息，请参阅 NCCL 文档和 UCX 文档。

自定义数据集。 有关使用自定义数据集的更多信息，请参阅 RAPIDS Container README。 Docker Hub 和 NVIDIA GPU Cloud 托管 RAPIDS 容器，并提供完整的可用标签列表。

pip

RAPIDS pip 软件包可在 NVIDIA Python Package Index 上获取，支持 CUDA 11 和 CUDA 12。

pip 额外先决条件

您系统上的 CUDA toolkit 版本必须与您安装的 pip CUDA 版本匹配 (-cu11 或 -cu12)。
glibc 版本： x86_64 wheels 需要 glibc >= 2.17。
glibc 版本： ARM 架构 (aarch64) wheels 需要 glibc >= 2.32 (仅支持 ARM Server Base System Architecture)。

SDK Manager (仅限 Ubuntu)

NVIDIA SDK Manager 为用户提供了一个图形用户界面 (GUI) 选项来安装 RAPIDS。它还尝试在安装或更新 RAPIDS 之前修复任何环境问题，使其成为 Linux 新用户的理想选择。

从其网站下载 SDK Manager 的 Ubuntu 版本（需要注册或登录 NVIDIA 开发者社区）。暂时不要安装。假定 .deb 文件将存储在您的主目录的 Downloads 文件夹中。如果不是，请将 sdkmanager_[version]-[build#]_amd64.deb 文件移动到您当前的 Download 文件夹。
使用此安装指南安装并运行 SDK Manager。对于 Ubuntu，请使用以下命令
```
sudo apt install ./sdkmanager_[version]-[build#]_amd64.deb
sdkmanager
```
当要求时登录，并按照 SDK Manager 的RAPIDS 安装说明进行操作。

Windows WSL2

Windows 用户现在可以通过在 Windows Subsystem for Linux 2 上使用 RAPIDS，在其本地机器上利用 GPU 加速的数据科学。WSL2 是 Windows 的一个功能，使用户能够直接在 Windows 上运行原生 Linux 命令行工具。使用此功能无需双启动环境，消除了复杂性并节省了时间。

WSL2 额外先决条件

操作系统： Windows 11，安装了 WSL2 的 Ubuntu (最低版本 20.04)。
WSL 版本： WSL2 (不支持 WSL1)。
GPU： 计算能力 Compute Capability 7.0 或更高版本的 GPU（推荐 16GB+ GPU 内存）。

限制

仅支持单 GPU。
不支持 GPU Direct Storage。

故障排除

使用 Conda 安装时，如果在访问仓库数据时出现 http 000 connection error 错误，请运行 wsl --shutdown 然后重启 WSL 实例。

使用 Conda 或 pip 安装时，如果出现 WSL2 Jitify fatal error: libcuda.so: cannot open shared object file 错误，请遵循此 WSL 问题中的建议来解决。

使用 Docker Desktop 安装时，如果容器拉取命令成功，但运行命令无限期挂起，请确保您的 Docker Desktop 版本 >= 4.18。

WSL2 SDK Manager 安装

NVIDIA 的 SDK Manager 为 Windows 用户提供了一个图形用户界面 (GUI) 选项来安装 RAPIDS。它还尝试在安装或更新 RAPIDS 之前修复任何环境问题，使其成为 WSL 新用户的理想选择。

在 Windows 主机上安装最新的 NVIDIA 驱动程序。
从其网站下载 SDK Manager 的 Ubuntu 版本（需要注册或登录 NVIDIA 开发者社区）。暂时不要安装。其余说明假定 .deb 文件将存储在您的主目录的 Downloads 文件夹中。如果不是，请根据您的系统需要更改目录。
根据 Microsoft 的说明安装或更新 WSL2 和 Ubuntu 22.04 或 Ubuntu 24.04 软件包。要从命令行安装 Ubuntu 24.04，请使用以下命令
```
wsl --install -d Ubuntu-24.04
```
这将使用 WSL2 在您的 Windows 主机系统中安装并启动 Ubuntu。请记住您的 sudo 密码，因为接下来的两步将需要它。
通过将此命令粘贴到您的命令行中，在 Ubuntu 内安装并运行 SDK Manager。此命令将从您的 WSL2 实例导航到您的 Windows 用户 Downloads 文件夹，并安装您已下载的最新 SDK Manager .deb 文件。您需要输入安装 Ubuntu 时创建的 sudo 密码。
```
sudo apt update && sudo apt install wslu -y
cd "$(wslpath -au "$(cmd.exe /c 'echo %USERPROFILE%' | tr -d '\r')")/Downloads"
sudo apt install "$(ls -t ./sdkmanager_*_amd64.deb | head -n 1)" -y
sdkmanager
```
当要求时登录，并按照此处的 SDK Manager RAPIDS 安装说明进行操作。

WSL2 Conda 安装

根据 Microsoft 的说明安装 WSL2 和 Ubuntu 发行版。
在 Windows 主机上安装最新的 NVIDIA 驱动程序。
登录到 WSL2 Linux 实例。
使用我们的Conda 说明在 WSL2 Linux 实例中安装 Conda。
使用 RAPIDS Release Selector 通过 Conda 安装 RAPIDS。
运行以下代码检查 RAPIDS 安装是否正常工作
```
import cudf
print(cudf.Series([1, 2, 3]))
```

WSL2 Docker Desktop 安装

根据 Microsoft 的说明安装 WSL2 和 Ubuntu 发行版。
在 Windows 主机上安装最新的 NVIDIA 驱动程序。
安装最新的 Docker Desktop for Windows
登录到 WSL2 Linux 实例。
根据您的期望配置，使用 RAPIDS Release Selector 生成并运行 RAPIDS docker 命令。
在 Docker 实例内部，运行以下代码检查 RAPIDS 安装是否正常工作
```
import cudf
print(cudf.Series([1, 2, 3]))
```

WSL2 pip 安装

根据 Microsoft 的说明安装 WSL2 和 Ubuntu 发行版。
在 Windows 主机上安装最新的 NVIDIA 驱动程序。
登录到 WSL2 Linux 实例。
遵循此有用的开发者指南，然后在 WSL2 实例中安装 WSL 特定的CUDA 11 或CUDA 12 Toolkit（不含驱动程序）。
- 安装的 CUDA Toolkit 版本必须与 pip wheel 版本匹配 (-cu11 或 -cu12)
- 任何 CUDA 12 CTK 都将与 RAPIDS -cu12 pip 软件包配合使用
使用release selector命令在 WSL2 Linux 实例上安装 RAPIDS pip 软件包。
运行以下代码检查 RAPIDS 安装是否正常工作
```
import cudf
print(cudf.Series([1, 2, 3]))
```

从源代码构建

要从源代码构建，请查看每个 RAPIDS GitHub README，例如 cuDF 的源环境设置和构建说明。选择器工具中提供了更多链接。如果需要额外帮助，请通过我们的 Slack 频道联系我们。

下一步

安装 RAPIDS 库后，最好的入门方式是我们的用户指南。我们的 RAPIDS.ai 主页以及我们的博客页面和 NVIDIA Developer Blog 也提供了大量信息。我们随时可以在我们的 RAPIDS GoAi Slack Channel 上为您提供帮助。