文档中心

Appearance

✨费用中心控制台

包含 CUDA 13.0、cuDNN 9 与兼容包的实验 Dockerfile (Ubuntu 24.04) ​

提示

本文中的平台预置镜像地址是示例。使用前，请在镜像中心或当前实例的预置镜像列表中确认当前可用区提供了对应仓库及 tag；如果列表中不存在，请改用页面显示的可用镜像地址。替换 Registry 域名并不能保证相同仓库或 tag 在其他环境或可用区中存在。

本文 Dockerfile 面向一种受限场景：应用必须使用 CUDA 13，但当前可用区的宿主机 NVIDIA 驱动由平台维护，用户无法通过容器内操作升级驱动。适用条件和限制请见 Dockerfile 后的说明。

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

ENV PATH=/usr/local/cuda/bin:/usr/local/cuda-13.0/bin${PATH:+:${PATH}} \
    LD_LIBRARY_PATH=/usr/local/cuda-13.0/compat:/usr/local/cuda/lib64:/usr/local/cuda-13.0/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 --no-install-recommends \
        ca-certificates \
        wget \
        build-essential \
    && rm -rf /var/lib/apt/lists/* \
    && wget https://developer.download.nvidia.com/compute/cuda/13.0.0/local_installers/cuda_13.0.0_580.65.06_linux.run \
    && sh cuda_13.0.0_580.65.06_linux.run --toolkit --silent --override \
    && echo '/usr/local/cuda/lib64' >> /etc/ld.so.conf \
    && echo '/usr/local/cuda-13.0/lib64' >> /etc/ld.so.conf \
    && ldconfig \
    && rm cuda_13.0.0_580.65.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 \
    && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
        cuda-compat-13-0 \
        cudnn9-cuda-13 \
    && echo '/usr/local/cuda-13.0/compat' > /etc/ld.so.conf.d/cuda-compat-13-0.conf \
    && 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 API 仍是 12.8 时，CUDA 13 应用可能报出 NVIDIA driver 太旧、CUDA 初始化失败或 No accelerator ... available。本文镜像通过安装 CUDA 13 forward compatibility 兼容包，让容器内应用进程优先加载兼容包提供的用户态 libcuda.so.1。它的目标是在平台暂未升级宿主机 NVIDIA 驱动时，验证 CUDA 13 应用是否还能启动、识别 GPU，并完成目标 workload。

只有同时满足以下条件时，才建议使用本文 Dockerfile：

  1. 应用镜像必须使用 CUDA 13，暂时不能降级到 CUDA 12.x。
  2. 宿主机 NVIDIA 驱动版本低于 CUDA 13.0 GA 原生运行要求，例如低于 580.65.06。
  3. 宿主机驱动由平台维护，用户不能在开发机、任务或推理服务容器内自行升级。
  4. 目标 GPU 和驱动分支属于 NVIDIA CUDA forward compatibility 支持范围。

如果宿主机驱动已经满足 CUDA 13.0 原生运行要求，请不要使用本文 Dockerfile。此时继续把 /usr/local/cuda-13.0/compat 放在最前面，反而可能覆盖宿主机注入的原生新版本 libcuda.so.1。请改用不含兼容包的 CUDA 13.0 + cuDNN 9 Dockerfile。

警告

本文 Dockerfile 不能升级宿主机 NVIDIA 驱动，也不能保证所有 CUDA 13 kernel 特性都可用。它只尝试解决 CUDA 13 应用进程加载到旧版用户态 libcuda.so.1 的问题。长期生产使用仍应优先使用驱动版本已经满足 CUDA 13 要求的可用区或平台环境。

下游镜像继承要求 ​

如果使用本文镜像作为基础镜像继续构建 PyTorch、SGLang、vLLM 或其他 CUDA 13 应用镜像，下游 Dockerfile 仍需保留兼容包路径的加载顺序。不要用新的 ENV LD_LIBRARY_PATH=... 覆盖掉 /usr/local/cuda-13.0/compat；如果确需重写，必须把该路径放在最前面。

language-dockerfile
ENV LD_LIBRARY_PATH=/usr/local/cuda-13.0/compat:/usr/local/cuda/lib64:/usr/local/cuda-13.0/lib64:/usr/lib/x86_64-linux-gnu${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}

下游镜像安装框架依赖后，仍建议重新运行本文的 LD_DEBUG 和 cuDriverGetVersion 检查。以 SGLang 0.5.14、PyTorch 2.11.0+cu130 和 DFlash 推理服务为例，只有应用进程优先加载兼容包中的 libcuda.so.1 后，CUDA 13 运行时才可能正常初始化。

什么时候改用普通 CUDA 13 镜像 ​

本文 Dockerfile 面向旧版但受支持的数据中心 GPU 驱动分支上的兼容性验证。它安装 cuda-compat-13-0，并把 /usr/local/cuda-13.0/compat 放在 LD_LIBRARY_PATH 最前面，使 CUDA 13 应用进程优先加载兼容包中的 libcuda.so.1。

如果宿主机驱动已经原生支持 CUDA 13.0，例如 Linux 驱动版本为 580.65.06 或更高，且应用进程中的 CUDA Driver API 显示 13.0 或更高，请使用普通 CUDA 13.0 + cuDNN 9 Dockerfile。两类镜像建议使用不同镜像标签，例如：

language-text
cuda-13.0-cudnn9:stable
cuda-13.0-cudnn9-compat:r570-experiment

不要把兼容包实验镜像当成所有 CUDA 13 场景的统一基础镜像。兼容包路径一旦排在 LD_LIBRARY_PATH 最前面，就可能覆盖新驱动环境中由宿主机注入的原生 libcuda.so.1。

Dockerfile 说明 ​

这个 Dockerfile 与普通系统级 CUDA 镜像的关键差异在于：安装 cuda-compat-13-0 后，显式把 /usr/local/cuda-13.0/compat 放在 LD_LIBRARY_PATH 的最前面。这样做是为了让 CUDA 13 应用进程优先加载兼容包中的 libcuda.so.1，而不是容器运行时注入到 /usr/lib/x86_64-linux-gnu/ 下的宿主机 libcuda.so.1。

关键环境变量 ​

language-dockerfile
ENV PATH=/usr/local/cuda/bin:/usr/local/cuda-13.0/bin${PATH:+:${PATH}} \
    LD_LIBRARY_PATH=/usr/local/cuda-13.0/compat:/usr/local/cuda/lib64:/usr/local/cuda-13.0/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}}

LD_LIBRARY_PATH 的顺序是本实验的核心。/usr/local/cuda-13.0/compat 必须排在最前面，否则应用可能继续加载宿主机注入的旧版 libcuda.so.1。如果应用进程中看到的 CUDA Driver API 仍然是 12.8，说明兼容库没有生效。

安装 CUDA 13.0 Toolkit ​

language-dockerfile
RUN apt-get update && \
    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
        ca-certificates \
        wget \
        build-essential \
    && rm -rf /var/lib/apt/lists/* \
    && wget https://developer.download.nvidia.com/compute/cuda/13.0.0/local_installers/cuda_13.0.0_580.65.06_linux.run \
    && sh cuda_13.0.0_580.65.06_linux.run --toolkit --silent --override \
    && echo '/usr/local/cuda/lib64' >> /etc/ld.so.conf \
    && echo '/usr/local/cuda-13.0/lib64' >> /etc/ld.so.conf \
    && ldconfig \
    && rm cuda_13.0.0_580.65.06_linux.run

该步骤使用 CUDA 13.0.0 的 runfile (local) 安装包，只安装 Toolkit，不在容器内安装 NVIDIA Driver。容器运行时仍必须使用平台宿主机提供的 GPU 驱动。

安装兼容包与 cuDNN ​

language-dockerfile
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 \
    && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
        cuda-compat-13-0 \
        cudnn9-cuda-13 \
    && echo '/usr/local/cuda-13.0/compat' > /etc/ld.so.conf.d/cuda-compat-13-0.conf \
    && 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-compat-13-0 提供 CUDA 13 forward compatibility 所需的用户态驱动库。cudnn9-cuda-13 提供面向 CUDA 13 的 cuDNN 9.x 运行库和开发文件。

验证兼容包是否生效 ​

镜像构建完成并用于带 GPU 的开发机、任务或推理服务后，先验证应用进程实际加载的是哪个 libcuda.so.1。

language-bash
LD_DEBUG=libs python - <<'PY' 2>&1 | grep -E 'libcuda|cuda-13|compat' | head -50
import ctypes
ctypes.CDLL("libcuda.so.1")
PY

如果兼容包生效，输出中应优先出现类似路径：

language-text
/usr/local/cuda-13.0/compat/libcuda.so.1

然后用 CUDA Driver API 查询应用进程看到的驱动能力：

language-bash
python - <<'PY'
import ctypes
v = ctypes.c_int()
cuda = ctypes.CDLL("libcuda.so.1")
cuda.cuInit(0)
cuda.cuDriverGetVersion(ctypes.byref(v))
print(v.value)
print(f"{v.value // 1000}.{(v.value % 1000) // 10}")
PY

如果仍然输出 12080 / 12.8，说明进程仍在加载宿主机注入的旧版 libcuda.so.1，兼容包没有生效。此时应先检查 LD_LIBRARY_PATH，不要继续排查 SGLang、PyTorch 或 DFlash 参数。

信息

nvidia-smi 展示的是宿主机驱动信息，不一定能证明当前 Python 进程已经加载兼容包。排查 CUDA 13 应用栈时，请优先使用上面的 LD_DEBUG 和 cuDriverGetVersion 结果。

确认 CUDA Driver API 后，再验证 PyTorch：

language-bash
python - <<'PY'
import torch
print(torch.__version__)
print(torch.version.cuda)
print(torch.cuda.is_available())
print(torch.cuda.get_device_name(0))
PY

如果 torch.version.cuda 是 13.0，但 torch.cuda.is_available() 仍为 False，请回到前面的 libcuda.so.1 加载顺序和 CUDA Driver API 结果继续排查。

失败时如何判断下一步 ​

  • 如果容器内没有 /usr/local/cuda-13.0/compat/libcuda.so.1，说明 cuda-compat-13-0 没有正确安装。
  • 如果文件存在，但 LD_DEBUG 显示优先加载 /usr/lib/x86_64-linux-gnu/libcuda.so.1，说明动态库路径顺序不正确。
  • 如果 cuDriverGetVersion 已经显示 13.0 或更高，但 PyTorch、SGLang、FlashInfer 或 DFlash 仍失败，说明问题已经进入具体框架或 CUDA kernel 特性层面。此时建议记录完整错误，换用原生支持 CUDA 13 的宿主机驱动进行对照。
  • 如果实验目标是长期运行生产服务，优先推动宿主机驱动升级到 CUDA 13 所需版本，而不是长期依赖兼容包。