Kohya_ss 安装排错手册：LoRA 训练环境搭建的完整避坑指南

Kohya_ss 安装排错手册LoRA 训练环境搭建的完整避坑指南【免费下载链接】kohya_ss项目地址: https://gitcode.com/GitHub_Trending/ko/kohya_ssKohya_ss 是面向 Stable Diffusion 的 LoRA 训练与模型微调 GUI 工具Kohya_ss安装 与排查通常卡在 Python 版本、路径空格、CUDA 环境和 tkinter 这几处。本文按报错现象分组覆盖环境准备、安装依赖、GPU 配置、GUI 启动到显存调优的完整流程每条都给出可直接执行的命令和官方文档入口帮你少走弯路。环境准备阶段Python、Git 与路径报错Python 版本报错must be 3.10.9 and 3.13.0现象跑 setup 时看到The Python version must be 3.10.9 and 3.13.0。根因setup_common.py 把合法区间写死为 3.10.9 到 3.13.0 以下你当前解释器多半是 3.9 或 3.13/3.14。解法python --version确认当前版本安装 3.11.x或改仓库根目录的.python-version让 uv 拉取指定版本多版本共存建议用 conda 或 pyenv 管理Git 子模块更新失败现象clone 后 setup 卡在子模块步骤或报 submodule 错误。根因clone 时没带--recursive或 Git 不在 PATH 里。解法完整克隆git clone --recursive https://gitcode.com/GitHub_Trending/ko/kohya_ss已 clone 的仓库补拉git submodule update --init --recursive用git --version确认 Git 已装并加入 PATH路径含空格直接报错现象验证阶段抛Invalid path: contains spaces。根因check_path_with_space 检测到当前目录路径里有空格GUI 明确不支持。解法把仓库移到无空格路径如C:\AI\kohya_ss或/home/user/kohya_ss删掉 venv 后重跑 setup。安装与依赖阶段bitsandbytes、pip 冲突与环境污染bitsandbytes 装不上或优化器选项缺失现象装依赖时 bitsandbytes 失败或 LoRA 训练选adamW8bit等 8bit 优化器时报警告。根因bitsandbytes 与 torch/CUDA 版本强绑定Windows 还需专门的处理。解法Windowspython setup/update_bitsandbytes.py或在 setup 菜单里强制安装指定版本Linux一般由 uv 自动处理无需手动干预参考 docs/Installation/pip_windows.md 的可选步骤pip 依赖版本冲突现象pip install时出现resolution failed或 conflicting dependencies。根因全局环境里已有旧版 torch/transformers与 requirements 冲突。解法优先用 uv 方法./gui-uv.sh独立环境最稳用 pip 时先python -m venv venv隔离再pip cache purge清缓存仍冲突就检查requirements.txt的具体版本要求venv 外模块污染现象check_local_modules提示Modules installed outside the virtual environment were found。根因全局 pip 装了同名包venv 优先命中了错误版本。解法按提示deactivate后卸载全局多余包再重建 venv。GPU 与 CUDA 阶段torch 找不到 GPU、显存不足、利用率低torch 报 CUDA not available现象validate 输出Torch reports GPU not available。根因torch 装成了 CPU 版或 CUDA toolkit 与 torch 的 CUDA 版本对不上。解法nvidia-smi查看驱动与 CUDA 版本按 docs/Installation/uv_linux.md 装对应 CUDA 12.8 的 torch训练时显存不足OOM现象加载模型或训练中途报CUDA out of memory。根因batch_size 偏大叠加高分辨率显存被吃满。解法降 batch_size改用梯度累积启用 xformers必要时加--lowram仍不够就考虑云 GPUTesla V100 GPU 利用率偏低现象V100 上训练 LoRA 时 GPU 利用率长期上不去也难指定非默认 GPU。根因默认优化器和小 batch 让 GPU 喂不饱。解法按 docs/troubleshooting_tesla_v100.md换adamW8bit优化器、调大 batch_size并在 setup 里显式指定 GPU ID。GUI 启动阶段tkinter 缺失与 headless 卡住ModuleNotFoundError: No module named tkinter现象启动 GUI 时提示找不到 tkinter。根因Linux 发行版默认不带 Tk。解法Ubuntu/Debiansudo apt-get install python3.11-tk python3.11-venvWindows重装 Python 时勾选 tcl/tk and IDLEmacOS用 pip 方法并安装 python-tk远程或 SSH 服务器上 GUI 卡住现象远程跑起来后进程不动、无响应。根因本地文件选择框和覆盖确认弹窗在 headless 环境无法交互把服务卡死。解法启动时加--headless --listen 127.0.0.1 --server_port 7860。装好后的验证流程与进阶云部署安装完成后的三项自检目的确认环境真的就绪避免训练时才暴露问题。操作python setup/validate_requirements.py验证依赖与 torch 后端python setup/check_local_modules.py排查 venv 外污染python setup/debug_info.py导出系统、Python 与 GPU 信息备查本地装不动时的云方案现象本地无可用 NVIDIA GPU 或系统过旧。根因硬件或驱动限制。解法用容器化部署参考 docs/installation_docker.md或用 Runpod 云 GPU环境一致性好、省去本地配置。排错时优先盯三处Python 版本是否落在 3.10.9 到 3.13.0、路径有没有空格、torch 是否匹配你的 CUDA。装完用setup/validate_requirements.py和 debug_info.py 各跑一遍多数问题就能在启动前拦住。更多细节以仓库docs/Installation/下的平台文档为准。【免费下载链接】kohya_ss项目地址: https://gitcode.com/GitHub_Trending/ko/kohya_ss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考