包含 CUDA 12.8.1 与 cuDNN 9 的 Dockerfile (Ubuntu 24.04)

下面是一个平台推荐的 Dockerfile 示例，用于构建包含系统级 CUDA 和 cuDNN 的 Docker 镜像。基于 Ubuntu 24.04 构建，并安装 CUDA 12.8.1 版本和 cuDNN 9.x。安装完成后，系统级 CUDA 环境就绪，可使用 nvcc 等开发编译工具。

警告

并非所有 CUDA Toolkit 版本均官方支持 Ubuntu 24.04（旧版本 CUDA 仅支持到 Ubuntu 22.04），因此在替换其他 CUDA 小版本时，请先去官方归档站确认其兼容性。

提示

在平台预置镜像不满足要求，或无法访问 Docker Hub 时，推荐您使用下方 Dockerfile 自行构建镜像。

FROM cr.infini-ai.com/infini-ai/ubuntu:24.04

ENV PATH=/usr/local/cuda/bin:/usr/local/cuda-12.8/bin${PATH:+:${PATH}} \
    LD_LIBRARY_PATH=/usr/local/cuda/lib64:/usr/local/cuda-12.8/lib64:/usr/lib/x86_64-linux-gnu${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} \
    CUDA_HOME=/usr/local/cuda \
    CPATH=/usr/include${CPATH:+:${CPATH}} \
    LIBRARY_PATH=/usr/lib/x86_64-linux-gnu${LIBRARY_PATH:+:${LIBRARY_PATH}}

RUN apt-get update && \
    DEBIAN_FRONTEND=noninteractive apt-get install -y wget build-essential \
    && rm -rf /var/lib/apt/lists/* \
    && wget https://developer.download.nvidia.com/compute/cuda/12.8.1/local_installers/cuda_12.8.1_570.124.06_linux.run \
    && sh cuda_12.8.1_570.124.06_linux.run --toolkit --silent --override \
    && echo '/usr/local/cuda/lib64' >> /etc/ld.so.conf \
    && echo '/usr/local/cuda-12.8/lib64' >> /etc/ld.so.conf \
    && ldconfig \
    && rm cuda_12.8.1_570.124.06_linux.run

RUN wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb \
    && dpkg -i cuda-keyring_1.1-1_all.deb \
    && apt-get update \
    && apt-get install -y cudnn-cuda-12 \
    && echo '/usr/lib/x86_64-linux-gnu' >> /etc/ld.so.conf \
    && ldconfig \
    && rm cuda-keyring_1.1-1_all.deb \
    && rm -rf /var/lib/apt/lists/*

本文包含的 Dockerfile 可用于在镜像中心基于 Dockerfile 构建镜像，或直接在开发机中构建镜像（使用 docker build / docker buildx build 命令）。

驱动版本兼容性说明：平台宿主机已安装的 CUDA 驱动程序（Driver）决定了 GPU 最终能支持的功能上限。因此，您在选择用于开发和编译的 CUDA 工具包（Toolkit）时，建议按照应用要求选择合适的 CUDA 版本。一般建议使用的 CUDA 版本不超过（即小于或等于）当前 CUDA 驱动程序所能支持的最高版本。在开发机中可使用 nvidia-smi 查询当前驱动版本。如驱动版本无法满足需求，可尝试更换可用区，或联系售后。

关于什么是系统级 CUDA 环境，可参考以下教程：

📖 手动安装特定版本的系统级 CUDA/cuDNN

📖 NVIDIA CUDA Toolkit 与 PyTorch 安装中的 CUDA 的区别

📖 获取系统级 CUDA/cuDNN 环境

Dockerfile 说明

从宏观上看，我们在为构建包含系统级 CUDA 的 Docker 镜像时，主要进行了以下优化设计：

• 分离库与驱动：使用 --toolkit 参数跳过显卡驱动器（Driver）的安装，仅安装 CUDA 开发库。因为容器内部必须依赖并继承物理宿主机的底层 GPU 驱动程序，强行在容器中安装驱动会导致底层设备环境冲突或不可用。
• 配置系统联动链：系统级设置 PATH 与 LD_LIBRARY_PATH 环境路径，并立即执行系统级刷新（ldconfig），确保安装应用开箱可用。
• 清除多余残留：安装后在单层 RUN 步骤内部迅速清理由于下载产生的安装包缓存，减小镜像体积。

配置运行时环境

FROM cr.infini-ai.com/infini-ai/ubuntu:24.04

运行时基于 Ubuntu 24.04 基础镜像。该镜像作为底层系统，提供了较新的系统级包管理和基础执行环境。

关键环境变量

ENV PATH=/usr/local/cuda/bin:/usr/local/cuda-12.8/bin${PATH:+:${PATH}} \
    LD_LIBRARY_PATH=/usr/local/cuda/lib64:/usr/local/cuda-12.8/lib64:/usr/lib/x86_64-linux-gnu${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} \
    CUDA_HOME=/usr/local/cuda \
    CPATH=/usr/include${CPATH:+:${CPATH}} \
    LIBRARY_PATH=/usr/lib/x86_64-linux-gnu${LIBRARY_PATH:+:${LIBRARY_PATH}}

通过配置 PATH 和各种链接库路径 LD_LIBRARY_PATH、CPATH、LIBRARY_PATH 等，确保系统及应用能够正确找到 CUDA 编译器（如 nvcc）以及相关的动态链接库和头文件。

安装 CUDA 并配置系统环境

RUN apt-get update && \
    DEBIAN_FRONTEND=noninteractive apt-get install -y wget build-essential \
    && rm -rf /var/lib/apt/lists/* \
    && wget https://developer.download.nvidia.com/compute/cuda/12.8.1/local_installers/cuda_12.8.1_570.124.06_linux.run \
    && sh cuda_12.8.1_570.124.06_linux.run --toolkit --silent --override \
    && echo '/usr/local/cuda/lib64' >> /etc/ld.so.conf \
    && echo '/usr/local/cuda-12.8/lib64' >> /etc/ld.so.conf \
    && ldconfig \
    && rm cuda_12.8.1_570.124.06_linux.run

该步骤首先通过 apt 安装下载工具 wget 以及编译必备的 build-essential。随后获取对应的 CUDA 运行文件进行静默免交互安装。在此过程中特别指定了 --toolkit 参数跳过安装显卡 Driver，因为容器必须使用外部宿主机的 GPU 驱动版本，在容器内注入驱动库会导致设备识别冲突。最后将新装的库路径写入系统配置并通过 ldconfig 刷新动态链接库缓存。

安装 cuDNN 并配置环境

RUN wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb \
    && dpkg -i cuda-keyring_1.1-1_all.deb \
    && apt-get update \
    && apt-get install -y cudnn-cuda-12 \
    && echo '/usr/lib/x86_64-linux-gnu' >> /etc/ld.so.conf \
    && ldconfig \
    && rm cuda-keyring_1.1-1_all.deb \
    && rm -rf /var/lib/apt/lists/*

利用官方提供的 cuda-keyring 在系统中添加 NVIDIA 官方针对于 Ubuntu 24.04 架构的包仓库。随后通过包管理器直接获取安装兼容 CUDA 12 系列的 cuDNN 库（cudnn-cuda-12），配置链接路径并清理安装包及缓存以减小最终镜像体积。

替换其他 CUDA 版本

如需安装其他能够支持 24.04 的 CUDA Toolkit 版本，请参考 NVIDIA CUDA Toolkit Archive 查找对应的 runfile (local) 文件名称。 在 Dockerfile 中需对应进行如下修改：

1. wget 命令中的下载链接和安装包名称。
2. ENV 等环境配置声明中的特定小版本路径数字（将其中的 cuda-12.8 修改为您所选的版本号）。