ModuleNotFoundError: No module named 'sqlalchemy' in ComfyUI

如果 ComfyUI 启动时报 ModuleNotFoundError: No module named 'sqlalchemy'，先把它当成核心启动依赖问题，而不是普通自定义节点问题。

在当前 ComfyUI 版本里，SQLAlchemy 会被 ComfyUI 自己的资产数据库代码在启动阶段导入。它缺失时，ComfyUI 可能还没到浏览器 UI 就直接停住。

.\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

真实报错长什么样

这次实战修复里，第一条真正阻塞启动的 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 目录。

快速判断

第一步：确认你用的是启动 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