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 安裝