RuntimeError: CUDA error: invalid device ordinal 是 PyTorch 等 CUDA 程序里高频报错，绝大多数情况是代码指定了不存在的 gpu_id，单卡机器 GPU 编号固定从 0 开始，没有 gpu_id=1、2 这类卡号，强行指定就会触发这个错误。很多开发者直接复制多卡训练脚本，脚本里写死 cuda:1、cuda:2，或者通过环境变量、分布式启动参数设置了大于 0 的卡号，放到只有一张显卡的服务器、本地 PC 上运行，CUDA 找不到对应编号设备，直接抛出设备序号非法异常；还有一部分情况是显卡驱动、CUDA 环境识别异常，nvidia-smi 识别不到 GPU，哪怕写 gpu_id=0 也会报错。解决思路优先先确认机器真实 GPU 数量与编号，再修改代码里 device 参数、环境变量、训练启动命令，单卡环境统一使用 gpu_id=0，同时避免混用多卡 DDP 参数；如果确认只有一张卡且指定 gpu_id=0 还报错，就要排查驱动、CUDA、PyTorch 版本匹配问题，确认显卡可以被正常识别，就能解决 invalid device ordinal 问题。
报错常见诱因清单
- 代码硬编码 device="cuda:1"、cuda:2，单卡机器只有 gpu_id=0
- 启动命令里设置 CUDA_VISIBLE_DEVICES=1，指定了不存在显卡序号
- DDP、多卡训练脚本直接复用，world_size、rank 参数没有改成单卡模式
- 显卡驱动异常、GPU 掉卡，nvidia-smi 看不到 GPU，gpu_id=0 也不可用
- 容器内没有透传显卡，容器环境识别不到主机 GPU
单卡、多卡 GPU 编号规则对比
| 机器类型 | 可用 gpu_id 范围 | 推荐写法 | 注意事项 |
|---|---|---|---|
| 单卡 GPU 机器 | 只有 0 | cuda:0 / CUDA_VISIBLE_DEVICES=0 | 不能写 1 及以上序号 |
| 双卡 GPU 机器 | 0、1 | cuda:0、cuda:1 | 两张卡序号独立 |
| 多卡 GPU 机器 | 0,1,2,...N-1 | 按实际识别序号使用 | 序号连续，从 0 起步 |
标准排查与修复步骤
- 执行 nvidia-smi，查看输出里 GPU 列表，确认能识别几张显卡、对应的编号
- 单卡环境，所有代码、启动参数统一使用 gpu_id=0
- 检查代码：torch.device ("cuda:0")，不要写 cuda:1
- 检查环境变量：启动前不要设置 CUDA_VISIBLE_DEVICES=1，需要限制卡就写 CUDA_VISIBLE_DEVICES=0
- 分布式训练脚本：单卡运行去掉 torch.distributed.launch/accelerate 多卡启动参数
- 再次运行程序，不再报 invalid device ordinal；如果仍然报错，排查驱动、容器显卡挂载、PyTorch-CUDA 版本匹配
【相关 FAQ】
问题 1：RuntimeError: CUDA error: invalid device ordinal，单卡机器 gpu_id 为什么只能从 0 开始？
回答 1：RuntimeError: CUDA error: invalid device ordinal 的底层规则是 CUDA 设备序号从 0 编排，单卡机器只存在 gpu_id=0，不存在 1、2 等序号，填写其他卡号就会触发 invalid device ordinal。
问题 2：单卡机器，代码写 gpu_id=0 还报 RuntimeError: CUDA error: invalid device ordinal 是什么原因？
回答 2：单卡机器写 gpu_id=0 仍然出现 RuntimeError: CUDA error: invalid device ordinal，一般是 nvidia-smi 识别不到 GPU，可能显卡驱动异常、容器未挂载 GPU、PyTorch 和 CUDA 版本不匹配。
问题 3：启动命令设置 CUDA_VISIBLE_DEVICES 会影响 RuntimeError: CUDA error: invalid device ordinal 吗？
回答 3：会，单卡机器如果设置 CUDA_VISIBLE_DEVICES=1，程序会去读取 gpu_id=1，直接触发 RuntimeError: CUDA error: invalid device ordinal，单卡环境这里应该设置为 0。
问题 4：多卡训练脚本拿到单卡机器运行，怎么修改避免 RuntimeError: CUDA error: invalid device ordinal？
回答 4：多卡训练脚本放到单卡机器运行，要删掉多卡启动参数，device 改为 cuda:0，gpu_id 固定为 0，不要使用 rank>0 的配置，防止 RuntimeError: CUDA error: invalid device ordinal。
【参考资料】
[2026-04-12]（RuntimeError: CUDA error: invalid device ordinal 报错解决）PyTorch 官方论坛
[2026-03-20]（单卡环境 GPU 编号规则，CUDA_VISIBLE_DEVICES 使用说明）掘金
[2025-11-08]（invalid device ordinal 设备序号错误常见场景汇总）CSDN
[2025-09-15]（nvidia-smi 查看 GPU 设备序号基础教程）NVIDIA 开发者文档
【免责声明】
本文为 PyTorch CUDA 报错排查经验整理，不替代 NVIDIA、PyTorch 官方文档；RuntimeError: CUDA error: invalid device ordinal 的排查还受容器、虚拟化、驱动版本、PyTorch 编译版本影响，最终环境配置以官方文档为准。