No module named 'llama_cpp' in ComfyUI: 修复 llama-cpp-python

如果你搜到的是 ModuleNotFoundError: No module named 'llama_cpp'，先记住一个关键点：导入名是 llama_cpp，但通常要安装的包名是 llama-cpp-python。

这类错误常见于本地 LLM、VLM、QwenVL GGUF、提示词增强器，或者某些 GGUF 文本推理 custom node 在启动时尝试导入 llama_cpp。

常见症状

启动日志里常见的样子有：

ModuleNotFoundError: No module named 'llama_cpp'

或者：

Cannot import <path> module for custom nodes: No module named 'llama_cpp'

在 Wonderful Launcher 的遥测里，这类错误也反复和 QwenVL GGUF 风格模块一起出现过：

Error loading module AILab_QwenVL_GGUF_PromptEnhancer: No module named 'llama_cpp'

这时 ComfyUI 本体可能依然能打开，但依赖 llama_cpp 的那一组 custom node 不会注册成功。

llama_cpp 到底是什么

llama_cpp 是 Python 导入模块名，它通常来自 llama-cpp-python 这个包，也就是 llama.cpp 的 Python 绑定。

在 ComfyUI 里，custom node 可能用它去跑本地 GGUF 语言模型或视觉语言模型。这和普通的 Stable Diffusion 图像 checkpoint 不一样，也和很多图像模型 GGUF loader 节点不是一回事。

常见对应关系大致是：

快速判断

如果你用的是 GitHub 官方 Windows 便携包，在便携包根目录运行：

.\python_embeded\python.exe -s -c "import sys; print(sys.executable)"
.\python_embeded\python.exe -s -m pip show llama-cpp-python
.\python_embeded\python.exe -s -c "import llama_cpp; print('llama_cpp OK')"

如果你是手动 Git 安装，先激活真正启动 ComfyUI 的那个 venv：

python -c "import sys; print(sys.executable)"
python -m pip show llama-cpp-python
python -c "import llama_cpp; print('llama_cpp OK')"

如果你用的是 ComfyUI Desktop 或其他托管启动器，就用应用自己的环境工具，不要默认去找 python_embeded 文件夹。

第 1 步：先判断它是不是当前阻塞点

下面这些情况，应该修 llama_cpp：

• 当前工作流用到了 QwenVL GGUF、VLM、本地 LLM 或提示词增强器节点
• 启动日志明确说某个 custom node 因为 llama_cpp 导入失败
• 工作流里对应那一组节点是红色的

下面这些情况，可以先不修它：

• ComfyUI 已经能打开，而且你眼前要跑的工作流根本不用本地 LLM / GGUF 文本节点
• 你当前真正缺的是图像 checkpoint、LoRA、VAE 或 ControlNet 模型
• 同时有很多不相关插件一起失败，而最早的错误并不是 llama_cpp

如果现在是很多包一起坏，先去看 ComfyUI Plugin Import Failed 或 ComfyUI 依赖冲突，别一上来再叠装一个原生包。

第 2 步：把包装进正确的 Python

如果你用的是官方 Windows 便携包：

.\python_embeded\python.exe -s -m pip install llama-cpp-python

如果你用的是手动 venv：

python -m pip install llama-cpp-python

这个基础命令有时会尝试源码编译。llama-cpp-python 官方也提供了 CPU 和部分 CUDA 预编译 wheel 索引。如果本地编译失败，不要反复重跑同一条命令，改用和你 Python / CUDA 版本匹配的 wheel。

第 3 步：如果只是为了恢复导入，先用 CPU 轮子

如果你现在的目标只是先让 custom node 导入成功，CPU wheel 往往是风险更低的第一步：

.\python_embeded\python.exe -s -m pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu

手动 venv 也是同理：

python -m pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu

只有当节点真的要跑本地 LLM 推理，而且 CPU 性能不够时，再考虑 CUDA wheel。选择 wheel 时先核对 Python 版本和 CUDA 版本，不要把别台机器上的命令直接贴过来。

第 4 步：先验证导入，再重启

运行：

.\python_embeded\python.exe -s -c "import llama_cpp; print(getattr(llama_cpp, '__file__', 'llama_cpp OK'))"

手动 venv：

python -c "import llama_cpp; print(getattr(llama_cpp, '__file__', 'llama_cpp OK'))"

如果这一步都还失败，ComfyUI 重启后也一样会失败。先把 Python 环境修到能 import 成功，再往下走。

常见失败场景

不要这样做

• 不要先去搜一个叫 llama_cpp 的包；最常见要装的是 llama-cpp-python
• 不要把包装进系统 Python，然后指望 ComfyUI 的 embedded Python 或 venv 能看到
• 不要只因为机器有 NVIDIA GPU，就盲目优先装 CUDA wheel
• 不要把它误当成普通图像模型 GGUF 问题，除非 traceback 里明确点名 llama_cpp
• 不要在没看 custom node 导入日志前，就直接重装整套 ComfyUI

Wonderful Launcher 在这里能帮什么

这个错误特别容易踩的坑，就是包装进了错误的 Python。Wonderful Launcher 的价值，是帮你把环境隔离开、把启动日志保留下来，也更容易定位到底是哪一个环境真的在启动 ComfyUI。

如果 llama_cpp 只是很多导入失败中的一个，优先修最早的那个依赖，不要盲目一层层往上叠包。

相关指南

• ComfyUI Plugin Import Failed
• ComfyUI-GGUF: Fix No Module Named 'gguf'
• ComfyUI 依赖冲突
• No module named 'onnx' or 'onnxruntime' in ComfyUI
• ComfyUI No Module Named Error: 什么情况下可以安全忽略

资料来源

• llama-cpp-python GitHub 仓库
• llama-cpp-python PyPI 包
• ComfyUI issue: No module named 'llama_cpp'
• ComfyUI Desktop issue: Qwen VL 与 llama-cpp-python wheel 安装