包含 CUDA 12.9.1 与 cuDNN 9 的 Dockerfile (Ubuntu 22.04)

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

提示

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

FROM cr.infini-ai.com/infini-ai/ubuntu:22.04-20240429

ENV PATH=/usr/local/cuda/bin:/usr/local/cuda-12.9/bin${PATH:+:${PATH}} \
    LD_LIBRARY_PATH=/usr/local/cuda/lib64:/usr/local/cuda-12.9/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.9.1/local_installers/cuda_12.9.1_575.57.08_linux.run \
    && sh cuda_12.9.1_575.57.08_linux.run --toolkit --silent --override \
    && echo '/usr/local/cuda/lib64' >> /etc/ld.so.conf \
    && echo '/usr/local/cuda-12.9/lib64' >> /etc/ld.so.conf \
    && ldconfig \
    && rm cuda_12.9.1_575.57.08_linux.run

RUN wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/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:22.04-20240429

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

关键环境变量

ENV PATH=/usr/local/cuda/bin:/usr/local/cuda-12.9/bin${PATH:+:${PATH}} \
    LD_LIBRARY_PATH=/usr/local/cuda/lib64:/usr/local/cuda-12.9/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.9.1/local_installers/cuda_12.9.1_575.57.08_linux.run \
    && sh cuda_12.9.1_575.57.08_linux.run --toolkit --silent --override \
    && echo '/usr/local/cuda/lib64' >> /etc/ld.so.conf \
    && echo '/usr/local/cuda-12.9/lib64' >> /etc/ld.so.conf \
    && ldconfig \
    && rm cuda_12.9.1_575.57.08_linux.run

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

安装 cuDNN 并配置环境

RUN wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/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 官方包仓库。随后通过包管理器直接获取安装兼容 CUDA 12 系列的 cuDNN 库（cudnn-cuda-12），配置链接路径并清理安装包及缓存以减小最终镜像体积。

替换其他 CUDA 版本

如需安装其他 CUDA Toolkit 版本，请参考 NVIDIA CUDA Toolkit Archive 查找对应系统（如 Ubuntu 22.04）的 runfile (local) 文件名称。 在 Dockerfile 中需对应进行如下替换及修改：

1. wget 命令中的下载链接和安装包名称（如将 cuda_12.9.1_575.57.08_linux.run 更改为您查找的文件名）。
2. ENV 等环境配置声明中的特定小版本路径数字（例如，如果装的是 12.5.1，则需把相关的路径由 cuda-12.9 修改为 cuda-12.5）。