ModuleNotFoundError: No module named 'sqlalchemy' in ComfyUI
修復 ComfyUI 便攜版啟動時報 No module named sqlalchemy 的問題，並判斷它是不是核心依賴大面積缺失的第一個信號。
如果 ComfyUI 啟動時報 ModuleNotFoundError: No module named 'sqlalchemy'，先把它當成核心啟動依賴問題，而不是普通自定義節點問題。
在當前 ComfyUI 版本里，SQLAlchemy 會被 ComfyUI 自己的資產數據庫代碼在啟動階段導入。它缺失時，ComfyUI 可能還沒到瀏覽器 UI 就直接停住。
最快修復
如果你用的是 GitHub Windows 便攜版，在包含 run_*.bat、python_embeded、ComfyUI 的根目錄運行：
.\python_embeded\python.exe -s -m pip show SQLAlchemy alembic
.\python_embeded\python.exe -s -m pip install "SQLAlchemy>=2.0" alembic
.\python_embeded\python.exe -s ComfyUI\main.py --windows-standalone-build如果修完 SQLAlchemy 後又出現下一個核心依賴錯誤，不要繼續靠猜一個個裝。直接看 ComfyUI 便攜版依賴損壞後的完整修複流程。
真實報錯長什麼樣
這次實戰修復裡，第一條真正阻塞啟動的 traceback 是：
File "...\ComfyUI\app\assets\database\queries\asset.py", line 1, in <module>
import sqlalchemy as sa
ModuleNotFoundError: No module named 'sqlalchemy'關鍵不只是缺了 sqlalchemy，而是它發生在 ComfyUI\app\assets 這條核心啟動路徑裡，不是某個單獨的 custom_nodes 目錄。
快速判斷
| 你看到的現象 | 含義 | 第一動作 |
|---|---|---|
No module named 'sqlalchemy' 出現在 Starting server 之前 | 核心依賴缺失 | 在 ComfyUI 使用的 Python 裡安裝 SQLAlchemy |
traceback 指向 app\assets\database | ComfyUI 自己啟動失敗 | 檢查 ComfyUI requirements，不要只看插件 |
修完後又出現 comfyui-frontend-package is not installed | 核心依賴不止缺一個 | 進入完整依賴修復流程 |
系統 Python 裡 pip show SQLAlchemy 正常，但 ComfyUI 仍失敗 | 裝錯 Python 了 | 使用 python_embeded\python.exe 或當前 venv |
| Torch 和 CUDA 還能正常 import | GPU 棧可能是好的 | 不要盲目重裝 Torch |
第一步：確認你用的是啟動 ComfyUI 的 Python
大部分修復失敗，不是包沒裝，而是包裝進了錯誤的 Python。
Windows 便攜版在便攜包根目錄運行：
.\python_embeded\python.exe -s -c "import sys; print(sys.executable)"
.\python_embeded\python.exe -s -m pip show SQLAlchemy alembic手動 Git 安裝版先激活虛擬環境：
.\venv\Scripts\activate
python -c "import sys; print(sys.executable)"
python -m pip show SQLAlchemy alembic如果你用的是 ComfyUI Desktop 或其他託管啟動器，使用應用自己的終端或環境工具，不要照搬便攜版的 python_embeded 路徑。
第二步：安裝缺失的核心依賴
Windows 便攜版：
.\python_embeded\python.exe -s -m pip install "SQLAlchemy>=2.0" alembic手動 venv：
python -m pip install "SQLAlchemy>=2.0" alembic為什麼同時帶上 alembic？因為當前 ComfyUI requirements 裡這兩個數據庫相關包是一起出現的。SQLAlchemy 已經缺失時，Alembic 也可能缺，下一次啟動可能會在同一條數據庫路徑上繼續失敗。
第三步：重啟，只讀新的第一條錯誤
再次啟動：
.\python_embeded\python.exe -s ComfyUI\main.py --windows-standalone-build成功啟動會看到：
Starting server
To see the GUI go to: http://127.0.0.1:8188如果下一條錯誤是 comfyui-frontend-package is not installed，看 comfyui-frontend-package is not installed in ComfyUI。
如果下一條錯誤還是 ComfyUI requirements 裡的核心包缺失，看 ComfyUI 便攜版依賴損壞後，如何不重裝 Torch 修好啟動。那說明 SQLAlchemy 只是第一個暴露出來的問題。
第四步：先保護正常的 Torch/CUDA
在跑大範圍安裝命令之前，先檢查 GPU 棧：
.\python_embeded\python.exe -s -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"如果這裡顯示 CUDA 版 PyTorch 且結果是 True，優先保護它。不要因為缺一個數據庫包就重裝 Torch 或 CUDA。
如果這裡是 False，或者 Torch 不能導入，先看 Torch not compiled with CUDA enabled。
不要做這些事
- 不要在系統 Python 裡運行普通
pip install sqlalchemy，而 ComfyUI 實際用的是 embedded Python - 不要還沒看第一條 traceback 就刪除 ComfyUI
- 不要因為數據庫包缺失就重裝 Torch/CUDA
- 不要把最後一行錯誤當成真正原因
- 不要在明顯缺很多核心依賴時繼續靠猜一個個裝包
Wonderful Launcher 能幫什麼
這種問題最怕看不到日誌、分不清 Python 環境。Wonderful Launcher 的價值不只是“啟動”，而是讓啟動日誌、環境邊界和修復過程更清楚。
如果你的環境從一個缺包跳到另一個缺包，問題通常不是 SQLAlchemy 本身，而是依賴棧已經漂移。
相關指南
- ComfyUI 便攜版依賴損壞後，如何不重裝 Torch 修好啟動
- comfyui-frontend-package is not installed in ComfyUI
- ComfyUI 依賴衝突
- Torch Not Compiled With CUDA Enabled
來源與實測
- 2026-05-18 Windows 便攜版修復實驗：啟動日誌從
ComfyUI\app\assets\database\queries\asset.py拋出ModuleNotFoundError: No module named 'sqlalchemy' - 同一實驗環境的
ComfyUI\requirements.txt包含SQLAlchemy>=2.0和alembic - 同一實驗環境在修復核心依賴和 frontend 包後，成功啟動到
http://127.0.0.1:8188
先按上面的步驟定位根因。還卡住時，可以下載 Wonderful Launcher 檢查目前機器；啟動器原生修復、任務日誌和執行階段檢查會集中在一起。credits 只用於圖片生成和按量工具。
下載 Wonderful Launcher查看 credits 方案這篇文件解決了你的問題嗎？
你的回饋會幫助我們優先補強真實 ComfyUI 排障文件。