kohya_ss 安装排错指南：从报错红屏到跑通 LoRA 训练的 4 步排查法
【免费下载链接】kohya_ss项目地址: https://gitcode.com/GitHub_Trending/ko/kohya_ss
kohya_ss 是一个图形化模型训练工具，能一键完成 Stable Diffusion 的 LoRA 训练与全量微调。但新手常卡在这里：setup 脚本装到一半蹦出一串红字，或者gui.sh双击后窗口一闪就没反应。本文按"自检 → 依赖 → 启动 → 调优"四个排查阶段，覆盖 kohya_ss 安装排错中最常见的报错，帮你对着关键词一步步修。
动手前先做环境自检
一步核对 Python 版本
看到的报错：The Python version must be >= 3.10.9 and < 3.13.0.原因：版本检查写死在setup/setup_common.py（L13-14），3.13 以下才放行，3.10.9 是下限。 处理：先跑python --version，不达标就装 3.11，Ubuntu 上sudo apt install python3.11 python3.11-tk python3.11-venv git。
路径带空格导致脚本静默失败
看到的报错：Invalid path: contains spaces.原因：setup/validate_requirements.py（L24-37）会直接抛异常拒绝运行，含空格的目录一律不支持。 处理：把仓库整个挪到无空格路径，例如C:\AI\kohya_ss或/home/user/kohya_ss，删掉旧 venv 再重跑 setup。中文目录名同理，一并避开。
Git 子模块没拉下来
看到的报错：clone 完直接跑 setup 报缺模块或找不到 sd-scripts 相关代码。 原因：kohya_ss 依赖子模块，普通git clone不会带它。 处理：在仓库根目录补一句git submodule update --init --recursive，或一开始就用git clone --recursive https://gitcode.com/GitHub_Trending/ko/kohya_ss完整克隆。
用自带诊断脚本先摸一遍底
报错信息不全时，别猜。直接跑python setup/debug_info.py，它会打印系统、Python、虚拟环境和 GPU 显存；再用python setup/check_local_modules.py检查有没有漏进虚拟环境之外的模块污染。
依赖与版本冲突集中爆发在这里
pip 装依赖报版本冲突
看到的报错：ERROR: Cannot install ... because these package versions have conflicting dependencies.原因：torch、transformers、accelerate 版本互相牵制，pip 自己解不出来。 处理：换 uv 通道。Linux 上优先跑./gui-uv.sh，它会自动创建.venv并按uv.lock装依赖，冲突最少；已用 pip 装烂的，删掉 venv 重来。
CUDA 与 PyTorch 版本对不上
看到的报错：Torch reports GPU not available或训练时CUDA error。 原因：nvidia-smi显示的驱动 CUDA 与 torch 编译时的 CUDA 不一致。 处理：先跑nvidia-smi看驱动支持的 CUDA 上限，再按官方文档选对应 wheel；setup 日志里Torch backend: nVidia CUDA x.x那行就是当前 torch 的后端，两个版本对不上就重装 torch。
Windows 上 bitsandbytes 装不上
看到的报错：bitsandbytes 导入失败或 8bit 优化器选项不可用。 原因：官方轮子对 Windows 支持有限，setup/setup_windows.py（L219-231）因此单独开了个菜单让你强制装指定版本。 处理：走 setup 菜单里的 "Force install Bitsandbytes 0.41.2"，不要自己pip install bitsandbytes-windows，那个选项文档里明确标了 "may cause issues"。
本地实在装不动时，备选是把仓库搬上云：Runpod 用./setup.sh -r一键装（见 docs/installation_runpod.md），Docker 走仓库根目录的Dockerfile，Colab 用kohya_ss_colab.ipynb。
首次启动与运行报错
No module named 'tkinter'
看到的报错：ModuleNotFoundError: No module named 'tkinter'，GUI 双击没反应。 原因：系统 Python 没带 Tcl/Tk，Windows 装 Python 时漏勾了 "tcl/tk and IDLE"。 处理：Ubuntu/Debian 装python3.11-tk，macOS 重装 brew python-tk，Windows 重装 Python 并勾上该选项。
GUI 起了但浏览器打不开
看到的报错：终端里 Gradio 在跑，浏览器连不上，或 WSL 里LD_LIBRARY_PATH警告刷屏。 原因：WSL 下共享库路径没设，gui.sh已做部分处理但 WSL2 建议手动补。 处理：跑export LD_LIBRARY_PATH=/usr/lib/wsl/lib/再启动；远程服务器可加 headless 参数走浏览器直连，参数以 docs/train_README.md 为准。
跑起来之后的显存与性能调优
显存不够时先降 batch_size
看到的报错：CUDA out of memory。 原因：模型 + 优化器状态超出显存，SDXL 全量微调尤其吃紧。 处理：先降 batch_size，用梯度累积补步数；再不行加--lowram把模型拆载到内存。
Tesla V100 上 GPU 利用率上不去
看到的报错：任务在跑，但nvidia-smi里利用率只有两三成。 原因：V100 对 64 位优化器利用率低，且多卡时可能选错卡。 处理：换adamW8bit优化器、适当加大 batch_size，并在设置里显式指定 GPU ID，官方给的参考是 docs/troubleshooting_tesla_v100.md。
bitsandbytes 优化器结果异常
看到的报错：换了 8bit 优化器后训练曲线和以前不一样。 原因：不同小版本的 bitsandbytes 行为有差异。 处理：用setup/update_bitsandbytes.py对齐版本，具体行为差异以仓库内文档为准。
收尾：一张速查表带走
排错顺序记住一条线：先确认 Python 版本和路径，再理依赖，然后看启动报错，最后才调性能——大多数"玄学问题"都在前两步。下表把高频报错和首选动作对齐了，卡住时直接查。
| 报错关键词 | 大概率原因 | 首选处理命令 |
|---|---|---|
Python version must be >= 3.10.9 and < 3.13.0 | Python 版本超区间 | python --version后改装 3.11 |
Invalid path: contains spaces | 目录路径含空格 | 挪到无空格路径，删 venv 重跑 |
cannot install ... conflicting dependencies | pip 解不开版本约束 | 改用./gui-uv.sh |
No module named 'tkinter' | 缺 Tcl/Tk | sudo apt install python3.11-tk |
CUDA out of memory | 显存不足 | 降 batch_size / 加--lowram |
Torch reports GPU not available | torch 与驱动 CUDA 不匹配 | 按nvidia-smi重装对应 torch |
下一步建议看仓库内的 docs/train_README.md 和 docs/LoRA/options.md，参数细节以仓库内文档为准。
【免费下载链接】kohya_ss项目地址: https://gitcode.com/GitHub_Trending/ko/kohya_ss
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
