★ FEATURED ARTICLE 1. 认识这个错误fbgemm.dll是什么为什么PyTorch离不开它1.1 错误出现的典型场景先说一下我在实际中遇到的这个报错。通常是在Windows环境下用pip装完PyTorch跑第一行import torch的时候控制台直接甩出OSError: [WinError 126] 找不到指定的模块。 Error loading fbgemm.dll 或其中一个依赖项有些朋友是在运行训练脚本时遇到有些是在Jupyter Notebook里import torch就崩还有的是在PyInstaller打包之后运行时才冒出来。不管是哪种场景这个错误一出现就意味着PyTorch的核心动态库没能正常加载整个框架基本没法用。我见过最迷惑的一次是某同事在Visual Studio里调试C项目时调用了Python嵌入API结果莫名其妙报这个错。其实也是同一个根源在Windows下加载fbgemm.dll时系统找不到它依赖的其他DLL。所以说这个问题不光是纯Python用户会遇到混合开发的场景也躲不开。1.2 fbgemm.dll在PyTorch中的角色先弄清楚fbgemm.dll是什么。它的全称是Facebook GEneral Matrix Multiplication是Facebook开源的一个高性能矩阵乘法库专门针对低精度、量化场景做了深度优化。PyTorch在CPU后端做某些算子的时候会调用它尤其是量化相关的算子比如torch.quantized_linear、torch.quantized_add等。但不要以为你只是普通训练不碰量化就不会用到它。实际上PyTorch导入时的初始化阶段就会加载fbgemm.dll因为它被捆绑在torch包的主库依赖链里。换句话说哪怕你只跑一个最简单的torch.rand(2,2)导入torch时也会去加载这个DLL。只要它加载失败整个import torch就会失败。另外要注意fbgemm.dll本身不是孤立的它依赖了C运行时库、OpenMP运行时库libomp或vcomp等其他组件。所以WinError 126经常不是fbgemm.dll本身缺失而是它依赖的某个底层库缺失或版本不对。1.3 WinError 126的本质含义Windows错误码126专业解释是“找不到指定的模块”。很多人看到这个信息第一反应是“fbgemm.dll这个文件不存在”于是去网上找这个dll下载、替换。这往往不能解决问题甚至会让事情更糟。因为WinError 126它指的是加载器Loader在尝试加载fbgemm.dll时发现这个模块本身可能存在但它依赖的某一个子模块找不到了。Windows加载DLL是一个递归过程加载fbgemm.dll时系统先看它的导入表发现它需要VCRUNTIME140.dll、MSVCP140.dll、libiomp5md.dll等然后一个个去找。任何一个找不到就会报126。类比一下就好比你要进一个房间门开了但房间里的某扇内门锁着你还是进不去。错误信息指着外门说“找不到”实际问题是内门的问题。所以排查思路必须从“依赖链”入手而不是死盯着fbgemm.dll这一个文件。2. 出错原因排查从环境到依赖逐个定位2.1 常见原因清单根据我自己踩过的坑和帮别人排查的经历WinError 126大部分逃不出下面这几类原因典型场景特征缺少微软VC运行库精简版Windows、Windows Server核心版错误伴随VCRUNTIME140.dll缺失提示或者用Dependency Walker能看到缺失项Python位数不一致装了32位Python但安装了64位PyTorch报错前有架构不匹配的警告或者pip安装时选择了错误的包OpenMP运行时缺失系统没有安装Intel OpenMP相关组件libiomp5md.dllfbgemm.dll依赖表里libiomp5md.dll无法定位杀毒软件隔离DLL某些安全软件把torch包里的dll误删或隔离去torch/lib目录看可能发现文件数量不对或者文件大小异常conda环境与pip混用先conda install再pip install torch依赖被覆盖报错前可能还有其他DLL加载警告路径问题系统PATH被修改或者Python目录不在PATH里import其他模块正常只有torch失败其中前两类占了我遇到的八到九成。所以遇到这个错误我建议你先别急着卸载重装花十分钟按下面流程检查一遍。2.2 用依赖分析工具确认缺失的模块确认问题在哪一步最直接的办法是看依赖链。Windows下有个老牌工具叫作Dependency Walker虽然官方已经停止更新但对这种加载问题依然有效。不过它对现代DLL的解析有时不够准确我推荐用另一款开源工具——DependenciesGitHub上的luqez/Dependencies项目。操作步骤是这样的打开Python安装目录找到Lib\site-packages\torch\lib文件夹。在文件夹里找到fbgemm.dll。用Dependencies工具打开这个文件它会列出fbgemm.dll所有直接依赖的模块。逐个检查状态凡是显示为红色或者标记为“missing”的就是问题所在。我第一次用这个工具排查时发现fbgemm.dll依赖的libiomp5md.dll没有找到。后来检查发现PyTorch安装包里的lib\libiomp5md.dll明明存在但系统的加载路径没包含torch的lib目录。加上环境变量后问题解决。提示直接用系统自带的where /r命令可以快速定位某个DLL是否存在。比如在cmd里执行where /r C:\ fbgemm.dll但注意这个搜索可能很慢建议只搜Python目录。2.3 区分“dll缺失”和“dll依赖缺失”这是最有迷惑性的地方。错误信息只告诉你“Error loading fbgemm.dll”但它没说清楚是fbgemm.dll本身缺失还是它的依赖缺失。怎么区分很简单如果C:\Python310\Lib\site-packages\torch\lib\fbgemm.dll这个文件不存在那是真的缺失。可能是安装不完整、被杀毒软件删除或者你下载了一个阉割版。如果文件存在但依然报126那就是依赖缺失。这时就要继续检查依赖链。我遇到过一个很典型的案例某开发者的系统是Windows 10 LTSC版本这个版本经常被精简掉一些运行库。PyTorch装上后报126我检查了fbgemm.dll本身存在但用Dependencies一看缺了VCRUNTIME140_1.dll。这就是典型的系统级VC运行库缺失。还有一个冷门原因是Python环境里的DLL搜索路径问题。Windows在加载动态库时搜索顺序是可执行文件所在目录、系统目录、系统PATH目录、当前目录。如果你把Python装到了自定义目录或者某些软件修改了PATH导致torch的lib目录不在搜索范围内也可能出现126。当然torch本身会尝试通过修改加载路径来规避这个问题但有时候在某些嵌入式场景下还是会失败。3. 实操解决方案从简单到彻底逐步搞定3.1 方案一重装PyTorchCPU版/GPU版最简单粗暴但通常有效的方法就是卸载重装。但这里面有个关键点很多人重装时还是安装同一个版本那自然还是会报错。我的建议是先完全卸载再重新安装并且明确区分CPU版和GPU版。CPU版和GPU版的PyTorch捆绑的依赖库不同。CUDA版的fbgemm.dll可能依赖了CUDA运行时的某些组件而你的系统没装CUDA或者版本不一致就会报126。如果只是做常规推理或CPU训练用CPU版反而少很多麻烦。重装命令可以参考pip uninstall torch torchvision torchaudio pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu这里有个细节卸载时最好用pip uninstall -y而且要注意是否还有通过conda安装的残留。如果一个环境里同时存在conda和pip两个入口的torch很可能产生dll版本冲突。如果你必须使用GPU版那么确保你的CUDA版本和显卡驱动匹配。PyTorch官网会标明每个版本对应的CUDA版本别装错了。3.2 方案二安装Microsoft Visual C Redistributable这是最容易被忽略、也是我每次都先让用户尝试的方案。PyTorch的Windows版依赖了MSVC的运行库而Windows系统默认不一定带了最新版。去微软官网下载“Visual C 2015-2022 Redistributable”合并包包含x86和x64版本都装一遍。特别是强烈建议安装x64版本因为你的Python和PyTorch大概率是64位的。装完之后不用重启如果系统没让你重启的话直接重新打开Python试一下import torch。这个问题就解决了一大半。而且微软这个运行库包是一路向后兼容的装了最新的版本旧版库里对应的dll也会补齐。我遇到过一个情况系统里原来有vcruntime140.dll但缺vcruntime140_1.dll装上这个合并包后两个都有了。注意不要自己从某些“dll下载站”下载单独的VCRUNTIME140.dll这些网站很可能给你带毒或旧版文件。官方合并包是唯一可靠渠道。3.3 方案三手动放置或修复fbgemm.dll这个方案针对“fbgemm.dll文件本身缺失”的情况。先确认文件位置python -c import torch, os; print(os.path.dirname(torch.__file__))能执行导入就不会报错所以你要在报错前用其他方式定位。实际上如果报错已经发生直接打开Python的安装目录去site-packages/torch/lib下看。如果是手动安装的wheel包可以用解压工具打开torch‑x.x.x-cpXXX-cpXXX-win_amd64.whl看看里面是否有fbgemm.dll或者包是否完整。我自己遇到过一次很奇葩的情况当时磁盘空间不足pip安装过程中中断了导致部分文件没写进去fbgemm.dll文件大小只有0字节。这时候其实只需要删除torch相关包重新安装不需要手动拷贝什么。如果确实需要从其他环境拷贝fbgemm.dll要注意以下几点必须是位数一致64位对应64位的DLL。最好PyTorch版本也一致因为不同版本之间的二进制不一定兼容。拷贝到torch\lib目录后还要确保依赖项也被拷贝过来。所以手动放置只是权宜之计我一般不建议因为它没法解决依赖链问题。3.4 方案四使用conda环境隔离如果你想从根源上避免系统环境互相干扰的问题我的建议是使用conda管理Python环境。conda安装PyTorch的时候会自动处理大部分依赖特别是MKL、OpenMP这些底层库不会和系统的全局运行库打架。安装命令示例conda create -n torch_env python3.10 conda activate torch_env conda install pytorch torchvision torchaudio cpuonly -c pytorchconda的包管理粒度比pip细它在安装PyTorch时会同时安装所有依赖的动态库并且通过conda的环境机制确保这些库能被正确加载。如果你习惯了pip也可以在conda环境里用pip安装。但要注意conda和pip混用时依赖问题会更多。我的建议是如果你的主要工作是深度学习一开始就用conda建环境再用pip补充其他包尽量不要两个包管理器重复安装同一个包。3.5 方案五检查杀毒软件与系统PATH杀毒软件和系统防护软件把torch的dll当作威胁处理我之前觉得是玄学直到真遇到一次。某同事的电脑上装了某安全卫士在扫描时把torch目录下的部分DLL加入了隔离区导致fbgemm.dll或它的依赖在加载时找不到。直接去安全软件的白名单把整个site-packages\torch目录添加信任重新安装torch后问题解决。系统PATH的问题更容易被忽略。尤其是Windows Server环境下经常有人为了精简把C:\Windows\System32从PATH里删了或者把Python目录排在了错误位置。检查方法在cmd中输入echo %PATH%。确认C:\Windows\System32存在。确认Python的安装目录和Scripts目录在PATH中。如果在列表里发现了某些不寻常的路径比如网络磁盘映射先临时删除再试。如果PATH没问题但问题依然存在可以在环境变量里添加一项PYTHONPATHC:\your\python\Lib\site-packages\torch\lib但这种做法属于“补丁性修复”尽量在排查过程中使用做完验证后最好还是从根本上解决问题。3.6 进阶操作动态库搜索路径修复这一节是给喜欢刨根问底的朋友看的。Windows加载dll的搜索规则是固定的但Python本身可以通过os.add_dll_directory()来扩展搜索路径。如果你不想修改系统环境变量可以在导入PyTorch之前手动添加dll目录。在Python脚本开头加上这样一段import os os.add_dll_directory(rC:\Python310\Lib\site-packages\torch\lib) import torch但注意os.add_dll_directory在Python 3.8及以上版本才可用。而且如果你在执行import os之后才加上目录可能会因为顺序问题导致某些dll已经尝试加载了。实际上import os本身不会加载torch的dll所以这样写没问题。这种方式适合临时测试或者用于嵌入式场景中。之前我在用Cython把Python程序编译成可执行文件时就靠这个函数把torch的dll目录指进去解决了打包后运行报126的问题。4. 高级排查技巧与避坑实录4.1 用Dependencies工具深挖依赖链如果上述方案都没搞定你就需要用Dependencies工具来一个模块一个模块地查。具体操作如下下载并打开Dependencies点击File - Open选择fbgemm.dll。界面左侧会显示DLL依赖树。系统会高亮缺失项。逐个点击黄色或红色的依赖项看它们的完整路径。对于缺失的依赖项确认它应该属于哪个安装包。举个例子如果你看到libiomp5md.dll缺失那毫无疑问是Intel OpenMP运行时没装全。可以尝试从Anaconda的Library目录里找到这个dll拷贝到torch的lib目录但更好的方式是重新安装带MKL的Python环境。另一种方式是使用Process Monitor监控加载过程。Process Explorer里打开某进程查看已加载的dll列表看哪些加载失败了。不过这个门槛略高适合有Windows调试经验的朋友。4.2 常见问题速查表我整理了一张表基本覆盖了我遇到的所有126场景和对应解法具体报错信息或现象根本原因推荐解法提示fbgemm.dll找不到但文件存在依赖缺失通常VC运行库或OpenMP缺失安装VC 2015-2022运行库、安装Intel OpenMP提示fbgemm.dll找不到文件不存在安装不完整/被杀软隔离重新安装PyTorch白名单排除torch路径在conda环境下用pip安装PyTorch后报126conda与pip的OpenMP/VC库冲突改用conda安装或重装pip版本前先清理conda的mkl用PyInstaller打包后运行报126打包未包含torch依赖dll用os.add_dll_directory或编辑spec文件添加二进制32位Python环境安装64位PyTorch架构不匹配安装64位Python 3.8重装64位PyTorch每次import torch都报但重启后有时正常环境变量加载顺序乱保持系统PATH干净使用virtualenv/conda隔离远程桌面/无桌面服务器环境下报126系统缺少部分系统组件安装完整桌面版或安装Server with Desktop组件4.3 独家避坑经验最后分享几个实操心得都是我反复踩过坑后才总结出来的。第一不要过度依赖“修复DLL”软件。市面上的dll修复工具鱼龙混杂大概率解决不了126还可能引入更多问题。Windows的加载机制决定了不是把缺失的dll塞进System32就能搞定还要保证依赖链完整。第二优先使用官方或conda发布的预编译包。PyTorch的每个版本依赖的底层库版本是固定的如果你用源码编译或者从第三方下载的whl很可能在安装后出现dll版本冲突。我一个朋友从某论坛下载了一个“优化版torch”装上后报126换了官网包立刻就好了。第三看日志时不要只看第一行。报错信息里的“or one of its dependencies”经常被忽略但它才是关键。以后看到类似错误先默认是依赖问题而不是文件缺失问题。第四注意Windows事件查看器。有些情况下加载dll失败会在系统事件日志里写入详细记录。在事件查看器-Windows日志-应用程序里查找级别为“错误”的条目来源可能是“SideBySide”或“Application Error”里面会告诉你具体是哪个dll找不到。这个信息比Dependency Walker更权威。第五如果你在使用最新的Python版本注意兼容性。我曾经在Python 3.12刚出稳定版时安装了当时的PyTorch nightly版本结果报126。后来发现是nightly版本与Python 3.12的某些dll不兼容。后来等PyTorch正式版本发布后才解决。所以遇到怪异问题先检查Python版本是否在PyTorch官方支持列表里。4.4 一个完整的实测案例流程说一个我最近帮人解决的完整案例你可以照这个顺序走一遍。某开发者的环境Windows 11家庭版Python 3.1064位通过pip安装了torch 2.1.2cpu报WinError 126。第一步我让他检查文件是否存在dir C:\Users\xxx\AppData\Local\Programs\Python\Python310\Lib\site-packages\torch\lib\fbgemm.dll文件存在大小约1.5MB左右排除直接缺失。第二步让他安装VC Redistributable 2015-2022安装时勾选了x64和x86两个架构。安装完测试依然报错。第三步用Dependencies工具打开fbgemm.dll发现缺少libomp.dll。这个文件一般位于torch\lib目录下但检查后发现该文件也存在。于是怀疑是搜索路径问题。第四步临时用os.add_dll_directory指向torch\lib目录再import torch居然成功了。说明问题出在加载器的搜索路径上。第五步检查他的系统PATH发现他的一个第三方软件在PATH里加入了很奇怪的目录排在系统目录前面干扰了搜索。把那个目录移到后面或者删除后直接import torch就正常了。这个案例最有价值的部分是问题不是任何依赖缺失而是搜索路径顺序被打乱。如果没有Dependencies工具的帮助光重装是永远解决不了问题的。所以我的建议是遇到WinError 126先定位依赖链再尝试系统运行库然后考虑环境隔离最后检查PATH和杀软按这个顺序排查解决问题效率会高很多也会少走弯路。
阅读完成 · 觉得有帮助？
