ZLUDA完整教程：在AMD显卡上运行未修改的CUDA程序

ZLUDA完整教程：在AMD显卡上运行未修改的CUDA程序

【免费下载链接】ZLUDACUDA on non-NVIDIA GPUs项目地址: https://gitcode.com/GitHub_Trending/zl/ZLUDA

假设你的机器装着一张AMD显卡，而你想跑的软件是用NVIDIA的CUDA工具链编译的——比如CUDA版的llama.cpp，或某段CUDA训练脚本。没有N卡时这类程序通常直接报错退出，ZLUDA就是一个CUDA兼容层：它对应用伪装成NVIDIA的驱动库，把CUDA调用翻译成AMD后端执行，让你不需要改一行代码就能在非N卡上跑CUDA程序。本文按"先自检、再安装、后验证"的顺序走一遍完整流程。

📋 动手前自检：显卡与驱动门槛

花十分钟核对下面三点，有一条不满足就别往下走了，装上也跑不起来。

在Linux上可以用一条命令确认核显/独显的厂商和型号，再对照上表：

lspci | grep VGA

这条命令会打印出显示控制器的厂商与型号，Windows用户则直接在任务管理器或驱动中心看显卡名称即可。

另外两个硬性门槛：

• Windows：需要较新的AMD官方 Adrenalin 驱动，外加一套 HIP SDK（官方安装包或夜构建版均可，官方文档有对比，需要跑PyTorch/TensorFlow类软件时建议选带机器学习库的版本）。
• Linux：装好 HIP/ROCm 运行环境即可。

🧩 安装ZLUDA：从拿代码到启动

第一步：获取代码或预编译包

git clone https://gitcode.com/GitHub_Trending/zl/ZLUDA

把仓库克隆到本地；如果你不想自己编译，也可以直接从项目 Releases 下载预编译包。装好之后，核心文件都集中在一个目录里，后文统一记作<ZLUDA_DIRECTORY>（预编译包是zluda目录，源码编译则是target/release），里面有伪装的驱动库libcuda.so/nvcuda.dll以及一批CUDA性能库的兼容实现。

第二步：Windows——两种放置方式任选

方式A（推荐）用自带启动器包一层：

<ZLUDA_DIRECTORY>\zluda.exe -- <应用.exe> <应用参数>

把zluda.exe放在任意CUDA程序前面执行，ZLUDA就会接管驱动库的加载。想从Steam启动的程序也一样，在游戏属性的"启动选项"里填"C:\Games\zluda\zluda.exe" -- %command%即可：

方式B：把ZLUDA的全部文件（含nvcuda.dll）直接拷进应用所在目录，让程序按原路径加载到兼容层。

第三步：Linux——环境变量一行配好

LD_LIBRARY_PATH="<ZLUDA_DIRECTORY>:$LD_LIBRARY_PATH" ./your_app

这一行的作用是让动态链接器在找libcuda.so时优先命中ZLUDA提供的那份。官方文档还给了LD_AUDIT作为备选方案，原理类似。

🔎 装好怎么算成功：日志里看到什么

跑官方自检程序

仓库自带一个cuda_check，它会依次加载并初始化全部CUDA性能库：

zluda.exe -- cuda_check.exe

全部正常时，每行都会打印OK（nvcuda、nvml、cublas、cudnn、cufft、cusparse等），括号里标注了每个库实际映射到的HIP SDK文件。哪一行不是OK，就先查对应库的SDK依赖是否装对。

开trace看调用链

程序行为异常时，Windows下用zluda.exe --zluda-trace -- <应用>启动，Linux下按文档设置LD_LIBRARY_PATH指向 trace 目录。日志里每一行CUDA调用都带[ZLUDA_TRACE]前缀，参数和返回码一目了然；哪一行返回的不是CUDA_SUCCESS，问题基本就出在那。Windows的日志落在用户临时目录下的zluda文件夹里，提issue时打包附上即可：

三个高频坑

现象：报"CUDA驱动版本不足"之类错误。原因：Adrenalin驱动太旧，或Windows上没装HIP SDK。处理：更新驱动并安装HIP SDK，然后重启。

现象：提示找不到libcuda.so。原因：环境变量没把ZLUDA目录加进搜索路径。处理：改用上面那一行带LD_LIBRARY_PATH的启动命令。

现象：首次启动极慢，像卡死一样。原因：ZLUDA要现场编译应用里的每个PTX内核，大型应用首启本来就慢。处理：用zluda_precompile <路径>预先扫一遍并缓存编译结果。

📚 文档入口与版本跟踪

• 官方文档：docs/，快速上手、HIP SDK安装、trace排查都在里面；核心实现在 zluda/src/。
• ZLUDA处于快速迭代期，官方会定期把某个预发布版标记为稳定版。遇到问题先确认手上是不是最新版；确认无效再提issue，并附上trace日志。

【免费下载链接】ZLUDACUDA on non-NVIDIA GPUs项目地址: https://gitcode.com/GitHub_Trending/zl/ZLUDA