QGIS 报错 DLL load failed while importing _C 解决方法
发布于 更新于
ImportError: DLL load failed while importing _C 表示 Windows 找到了 PyTorch，但随后拒绝加载其底层的某个编译 DLL。通过插件将 torch 安装到 QGIS 的 Python 后，您可能会在 QGIS 中遇到这个错误，我们的插件也不例外。安装 Microsoft Visual C++ Redistributable（x64），然后重启 Windows。大多数电脑这样就能解决。
Traceback (most recent call last):
File "C:\...\site-packages\torch\__init__.py", line 141, in <module>
raise err
OSError: [WinError 126] The specified module could not be found.
Error loading "C:\...\site-packages\torch\lib\fbgemm.dll" or one of its dependencies.
ImportError: DLL load failed while importing _C: The specified module could not be found.
有些电脑会在相同故障中指出另一个文件，下面的修复方法仍然相同：
Error loading "C:\...\site-packages\torch\lib\shm.dll" or one of its dependencies.
适用于 Windows 10 和 11、QGIS 3.22 及更高版本，以及 PyTorch 2.4.0 至 2.8.0。这些 Windows wheel 会包含 fbgemm.dll。2.9.0 版本移除了该文件。
如果您的错误显示的是 [WinError 127] 而不是 126，请停在这里。这个错误表示 DLL 已加载，但其中缺少某个符号，原因是软件包之间存在版本不匹配，而不是本文讨论的故障。
快速修复
安装 Visual C++ Redistributable（x64）
从 aka.ms/vc14/vc_redist.x64.exe 运行 vc_redist.x64.exe。即使您已经安装了 x86 版本，也要选择 x64。它们是独立的软件包，而 torch 需要 x64。
重启 Windows
需要重启电脑，而不是重启 QGIS。安装程序会将部分工作留到重启时完成。
检查是否有第二个 Python
在命令提示符中运行 where python。如果结果超过一个，说明 Anaconda、Miniconda 或独立安装的 Python 正在与 QGIS 使用的 Python 发生竞争。
把多余的 Python 从 PATH 中移除
依次打开“开始”、“环境变量”、“编辑系统环境变量”、“环境变量”、“Path”。删除 QGIS 不使用的 Python 对应条目，然后退出 Windows 账户并重新登录。
如果错误没有变化，请继续执行修复 2。
检查是否生效
从“开始”菜单中的 QGIS 文件夹打开 OSGeo4W Shell，然后运行：
python -c "import torch; print(torch.__version__)"
如果单独一行显示版本号，且上方没有 traceback，就表示 DLL 已成功加载。现在在真正需要使用它的地方重复测试：打开 QGIS，依次打开 插件 > Python 控制台（Plugins > Python Console），然后运行 import torch。如果那里只出现一个空提示符，就是想要的结果。如果两次测试一项成功而另一项失败，说明它们运行的是不同的 Python，请回到第 3 步。
修复 2：缺少 fbgemm.dll 的依赖项
有些电脑已经安装了 Redistributable，但仍然缺少 libomp140.x86_64.dll。长期修复方法是升级到 PyTorch 2.9.0 或更高版本，该版本完全不再包含 fbgemm.dll。如果您必须固定使用旧版本，PyTorch 跟踪器上的用户报告称，把随免费的 Visual Studio Community 一同安装的 libomp140.x86_64.dll 复制进来后即可运行。这只是临时解决方法，绝不是维护者修复，而且没有任何 PyTorch wheel 会打包该文件。不要从下载网站获取散装 DLL。
如果错误没有变化，请继续执行修复 3。
修复 3：wheel 与电脑不匹配
在没有匹配 NVIDIA 驱动的电脑上安装 CUDA 构建版本，会在同一行失败。如果没有 NVIDIA GPU，请强制安装 CPU 构建版本：
pip install --force-reinstall torch --index-url https://download.pytorch.org/whl/cpu
如果有 GPU，请使用 PyTorch 安装页面针对您的 CUDA 版本提供的命令。在 conda 环境中，应使用 conda 而不是 pip 安装 torch，这样运行时库就会与软件包来自同一位置。
如果错误没有变化，请继续执行修复 4。
修复 4：杀毒软件在安装后删除了文件
打开“Windows 安全中心”（Windows Security），依次进入“病毒和威胁防护”（Virus and threat protection）、“保护历史记录”（Protection history）。恢复它从 site-packages 文件夹中删除的任何内容，将该文件夹加入排除项，然后重新安装 torch。安装过程显示成功，文件夹看起来也仍然内容齐全，因此屏幕上没有任何明显迹象会指向这里。
如果错误没有变化，请继续查看下方的“仍然无法解决？”。
为什么会发生
PyTorch 提供的是编译后的 DLL，而不是纯 Python。fbgemm.dll 及其在 torch/lib 中的相邻文件会链接 Microsoft C 运行库。当 Windows 找不到某个 DLL 自身的依赖项时，就会拒绝加载该 DLL。它会在依赖链的最上层，也就是负责执行导入的 torch 扩展模块 _C 上报告失败，这就是为什么错误信息会指出一个明明就在磁盘上的文件。
第二个原因是 Python 3.8。从该版本开始，系统路径、存放 DLL 或 PYD 文件的目录，以及通过 add_dll_directory() 添加的目录才会被搜索。PATH 和当前工作目录完全不再使用。因此，同时安装了 Anaconda 和 QGIS 的电脑可能会将错误 Python 的 torch/lib 交给加载器，而错误信息不会告诉您它最终选择了哪个。请从 QGIS 自己的“开始”菜单快捷方式启动 QGIS，不要从运行过 conda activate 的终端中启动。
仍然无法解决？
AI Segmentation 是我们的插件中会将 PyTorch 安装到 QGIS 的 Python 的那个，因此您可能会因它遇到这个错误。它的云端模式会在我们的服务器上运行模型，不需要本地 torch，但这并不能修复其他需要使用 torch 的插件。请将 QGIS 版本、完整 traceback 和插件版本发送至 stephane.barbot@terra-lab.ai。我们会告诉您属于四种情况中的哪一种。
常见问题
为什么错误指向 _C，而缺少的文件却是 fbgemm.dll？
_C 是负责执行导入的 torch 扩展模块，因此它位于依赖链的最上层，Windows 会在那里报告失败。上一行指出的文件 fbgemm.dll 或 shm.dll 通常确实存在于磁盘上。真正缺少的是该文件所依赖的内容。
哪些 PyTorch 版本会受到影响？
2.4.0 至 2.8.0 的 Windows wheel 会包含 fbgemm.dll。2.9.0 版本移除了该文件，因此升级可以消除这类特定故障。由于其他原因，例如在没有匹配驱动的电脑上安装 CUDA 构建版本，仍然可能出现 _C 相关错误提示。
WinError 126 和 WinError 127 有什么区别？
126 表示 Windows 找不到该模块或其依赖项之一，这就是本文讨论的故障。127 表示 DLL 已加载，但其中缺少某个符号，原因是两个软件包之间存在版本不匹配。上面的修复方法都无法解决 127。
我可以从 DLL 网站下载 libomp140.x86_64.dll 吗？
不可以。请从免费的 Visual Studio Community 安装中获取它，PyTorch 跟踪器上报告该临时解决方法的人就是从那里获得的。从下载网站获取的副本不一定是同一个文件，而且任何 PyTorch Windows wheel 都不会包含这个文件。
如果您在 GDAL 上遇到相同的错误措辞，_gdal 版本的这个错误有自己的修复方法。想了解 torch 加载后 AI 在 QGIS 中能做什么，请从 QGIS AI hub 开始。
