复现 GitHub 深度学习项目时，不要看到 CUDA 报错就立刻重装系统。先分清 NVIDIA 驱动、PyTorch 自带的 CUDA 运行时和本机 CUDA Toolkit，再判断问题出在哪一层。

一、先分清三个容易混淆的 CUDA 版本

很多环境问题都来自把下面三个版本当成同一回事。

查看方式	实际代表什么
nvidia-smi 中的 CUDA Version	当前驱动能够支持的最高 CUDA 版本
torch.version.cuda	当前 PyTorch 安装包构建时使用的 CUDA 版本
nvcc --version	本机 CUDA Toolkit 编译器版本

它们不一定完全相同。

使用 PyTorch 官方提供的 CUDA Wheel 时，程序运行主要依赖显卡驱动和安装包携带的 CUDA 运行时依赖，不能只根据本机 nvcc 版本判断环境是否兼容。

但如果项目需要编译 flash-attn、xformers、DCNv2 或自定义 CUDA 算子，本机 CUDA Toolkit、编译器和 GPU 架构就会重新变得重要。

二、先执行这组检查命令

1. 查看显卡和驱动

nvidia-smi

主要记录：

• GPU 型号
• Driver Version
• 显存容量
• 当前进程
• nvidia-smi 显示的 CUDA Version

注意，nvidia-smi 显示的 CUDA Version 不等于电脑已经安装了这个版本的 CUDA Toolkit。

2. 查看 Python 和 PyTorch

python --version
which python
pip show torch

Windows 可以执行：

where python
pip show torch

这里主要检查一个经常被忽略的问题：当前终端使用的 Python，是否真的是安装 PyTorch 的那个环境。

3. 检查 PyTorch 能不能识别 GPU

python - <<'PY'
import torch

print("PyTorch:", torch.__version__)
print("PyTorch CUDA:", torch.version.cuda)
print("CUDA available:", torch.cuda.is_available())
print("cuDNN:", torch.backends.cudnn.version())

if torch.cuda.is_available():
    print("GPU:", torch.cuda.get_device_name(0))
    print("Capability:", torch.cuda.get_device_capability(0))
PY

正常情况下，至少应该看到：

CUDA available: True
GPU: NVIDIA ...

如果 torch.version.cuda 是 None，通常说明安装的是 CPU 版本 PyTorch。

4. 查看本机 CUDA Toolkit

nvcc --version

如果提示找不到 nvcc，不一定意味着 PyTorch 无法使用 GPU。

对于只使用 PyTorch 官方预编译包的项目，本机没有 nvcc 也可能正常运行。只有需要编译 CUDA 扩展时，才必须重点处理 Toolkit 和编译器版本。

5. 生成完整环境报告

python -m torch.utils.collect_env

这条命令会汇总：

• PyTorch 版本
• Python 版本
• CUDA 和 cuDNN 信息
• 操作系统
• 编译器
• GPU 型号
• 驱动信息

遇到问题时，建议先保存这份输出。它比只发一张报错截图更容易定位问题。

三、用最小程序验证基础 CUDA

在运行整个项目之前，先确认 PyTorch 的基础 GPU 计算正常。

python - <<'PY'
import torch

assert torch.cuda.is_available(), "PyTorch 当前无法使用 CUDA"

x = torch.randn(2048, 2048, device="cuda")
y = x @ x

print("GPU:", torch.cuda.get_device_name(0))
print("Result:", y.mean().item())
print("Basic CUDA test passed")
PY

如果这段程序能够运行，但项目仍然报错，问题通常不在基础驱动层，而在项目依赖、第三方 CUDA 算子或者代码版本。

四、根据现象判断问题在哪一层

现象	优先排查
nvidia-smi 无法运行	NVIDIA 驱动、GPU 是否挂载、容器权限
import torch 报错	Python 环境、PyTorch 安装是否完整
torch.cuda.is_available() 为 False	是否安装了 CPU 版 PyTorch、驱动是否可见
基础 CUDA 测试成功，项目仍报错	requirements、项目代码、第三方算子
安装 flash-attn 等包时报错	CUDA Toolkit、GCC、PyTorch ABI、GPU 架构
终端能运行，Jupyter 或 VS Code 不能运行	Python 解释器或 Kernel 选错
容器内看不到 GPU	NVIDIA Container Toolkit、--gpus all 参数

这种分层排查比反复卸载 CUDA 更快。

五、安装依赖前先检查项目留下了什么

拿到 GitHub 仓库后，不要直接执行：

pip install -r requirements.txt

先检查这些文件：

README.md
requirements.txt
environment.yml
pyproject.toml
setup.py
Dockerfile
docker-compose.yml
.github/workflows/

它们可能分别提供：

• Python 版本
• PyTorch 版本
• CUDA 基础镜像
• 系统依赖
• 编译器要求
• 作者实际测试过的环境
• CI 中能够运行的版本组合

还要记录当前代码版本：

git rev-parse HEAD
git status

同一个仓库的不同提交，依赖要求可能已经变化。只记录仓库地址，不记录 Commit，很难做到真正复现。

六、创建独立环境，不要污染现有 Python

以 Conda 为例：

conda create -n paper-repro python=3.10 -y
conda activate paper-repro

然后根据项目要求，从 PyTorch 官方安装页面选择对应版本。

例如，项目明确要求某个 PyTorch 和 CUDA Wheel 时，应使用该版本对应的官方安装命令，不要随便把 PyTorch 升级到最新版。

安装完成后先检查：

python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"

确认基础环境正常，再安装其他依赖：

pip install -r requirements.txt

如果 requirements.txt 同时固定了 torch、torchvision 和 torchaudio，需要检查三个版本是否属于同一兼容组合。

PyTorch 官方的 Previous Versions 页面保留了历史版本的安装命令，可以用来核对。

七、什么时候适合使用 Docker

如果项目提供了 Dockerfile 或官方容器镜像，优先使用它通常更省时间。

先测试 Docker 能不能访问 GPU：

docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

如果能够看到 GPU，再构建项目镜像：

docker build -t paper-repro .

docker run --rm --gpus all -it \
  -v "$(pwd)":/workspace \
  -w /workspace \
  paper-repro

Docker 可以隔离 Python、系统库和 CUDA Toolkit，但它不能完全忽略宿主机。

宿主机仍然需要：

• 可用的 NVIDIA 驱动
• Docker 或其他容器运行时
• NVIDIA Container Toolkit
• 正确的 GPU 挂载参数

因此，“放进 Docker 就一定能运行”也是不准确的。

八、云 GPU 环境怎么用于论文复现

如果本地没有 NVIDIA GPU，或者驱动版本无法满足项目要求，可以选择带基础镜像的云 GPU 实例。

建议先按下面的顺序操作：

1. 根据项目要求选择 Python、PyTorch 和 CUDA 接近的基础镜像
2. 使用 SSH、JupyterLab 或 VS Code 连接实例
3. 克隆仓库并记录 Commit
4. 运行基础 CUDA 测试
5. 安装项目依赖
6. 运行仓库提供的最小 Demo
7. 成功后再下载完整数据集和模型
8. 保存环境信息和依赖清单

以算家云当前公开帮助文档为例，实例可以通过 SSH、JupyterLab 和 VS Code 使用。环境配置完成后，可以把系统盘内容保存为项目镜像。

但需要注意，保存项目镜像不包含数据盘内容。模型、数据集和实验结果如果放在数据盘，仍然要单独备份。

这里不建议一开始就下载几百 GB 的数据。先跑通最小输入，确认代码、模型和 CUDA 算子能够工作，再处理完整数据集。

九、复现成功后保存哪些信息

至少保存下面这些内容：

python -m torch.utils.collect_env > collect-env.txt
pip freeze > requirements-lock.txt
git rev-parse HEAD > git-commit.txt

如果使用 Conda：

conda env export --from-history > environment-history.yml

建议最终保留：

paper-repro/
├── README-repro.md
├── collect-env.txt
├── requirements-lock.txt
├── environment-history.yml
├── git-commit.txt
├── Dockerfile
├── run.sh
└── expected-output.txt

其中 README-repro.md 最好写清：

• 使用的 GPU
• Python、PyTorch 和 CUDA 版本
• 项目 Commit
• 安装命令
• 启动命令
• 最小输入
• 预期输出
• 已知问题

这样下次换机器或换云平台，不需要再从聊天记录和终端历史里找环境。

十、一个更稳妥的排查顺序

nvidia-smi 能否运行
        ↓
当前 Python 环境是否正确
        ↓
PyTorch 是否为 CUDA 版本
        ↓
torch.cuda.is_available() 是否为 True
        ↓
基础矩阵计算是否成功
        ↓
项目最小 Demo 是否成功
        ↓
第三方 CUDA 算子是否成功
        ↓
完整数据和训练任务

不要跳过前面的基础测试，直接跑完整训练。

环境问题越早暴露，排查成本越低。

常见问题

1. nvidia-smi 显示 CUDA 12，PyTorch 显示 CUDA 11.8，正常吗？

可能正常。

nvidia-smi 展示的是驱动能够支持的最高 CUDA 版本，torch.version.cuda 展示的是当前 PyTorch 构建使用的 CUDA 版本，两者不要求完全一致。

最终仍需运行 torch.cuda.is_available() 和基础 CUDA 测试确认。

2. 没有安装 nvcc，PyTorch 还能使用 GPU 吗？

使用官方预编译 PyTorch CUDA 安装包时，可能不需要本机安装完整 CUDA Toolkit。

如果需要编译 flash-attn、xformers 或自定义 CUDA 扩展，则通常需要匹配的 Toolkit 和编译环境。

3. 能不能直接把旧项目的 PyTorch 升级到最新版？

不建议直接升级。

旧项目可能依赖已经变化的 API、算子行为和第三方包。应优先复现作者明确记录或 CI 实际使用的版本，再决定是否升级。

4. Docker 内能运行，就代表环境完全复现了吗？

不一定。

还需要记录镜像版本、项目 Commit、模型权重、输入数据、启动参数和随机种子。容器只能解决环境隔离的一部分问题。

5. 保存云平台项目镜像后，数据集会一起保存吗？

不一定。以算家云公开规则为例，项目镜像保存系统盘内容，不包含数据盘。其他平台也需要分别检查系统盘、数据盘和持久化存储的规则。

参考资料

• PyTorch 官方安装页面
• PyTorch 历史版本安装命令
• NVIDIA CUDA Toolkit、驱动和架构对应关系
• NVIDIA Container Toolkit 安装文档
• 算家云 JupyterLab 基础镜像说明
• 算家云保存项目镜像说明

——————
发布时间：2026-08-14