Kohya_ss 三步跑通 LoRA 训练 GUI：环境自检、安装到报错补救
【免费下载链接】kohya_ss项目地址: https://gitcode.com/GitHub_Trending/ko/kohya_ss
Kohya_ss 是一个图形化的 Stable Diffusion 模型训练工具，让你用界面完成 LoRA 训练和模型微调。这篇指南带你按顺序完成 Kohya_ss 安装：先自检 Python 和显卡，再克隆仓库、装依赖、启动 GUI，最后处理高频报错。跟着做完，你就能在本地跑起第一个训练任务。
动手前：5 项环境自检
安装前先把这几项确认掉，缺什么补什么，能省掉后面一大半返工。
| 检查项 | 要求 | 怎么查 |
|---|---|---|
| Python | ≥ 3.10.9 且 < 3.13.0 | python --version |
| 显卡 | NVIDIA GPU（训练必需） | nvidia-smi |
| CUDA 工具包 | 12.8 | nvidia-smi右上角版本 |
| Git | 已安装并在 PATH 中 | git --version |
| 安装路径 | 不含空格、不含中文 | 看你要放的目录 |
Python 是运行整个项目的解释器；CUDA 是 NVIDIA 显卡的加速库，两者版本必须配套。
阶段一：准备环境
目标：装好 Python 和 CUDA，让系统具备跑训练的基础。
- 安装 Python 3.11.x，安装时勾选 "Add to PATH"。 用
python --version确认输出了版本号。 - 安装 CUDA 12.8 工具包，按系统选 Windows 或 Linux 包。 装完用
nvidia-smi确认显卡和驱动都能识别。 - 安装 Git，装完用
git --version验证。 备选：Linux 用户可sudo apt install git一步到位。
👉 卡在这一步？
- 症状：
python --version显示 3.9 或 3.13。原因：版本不在支持范围。处理：改装 3.11.x，别用 3.13。 - 症状：
nvidia-smi报找不到命令。原因：没装显卡驱动或工具包。处理：先装 NVIDIA 驱动，再装 CUDA 12.8。
阶段二：克隆仓库并安装依赖
目标：把代码拉到无空格路径，用uv一次性装好依赖。
- 把仓库克隆到无空格路径，例如
D:\ai\kohya_ss。git clone --recursive https://gitcode.com/GitHub_Trending/ko/kohya_ss--recursive会连子模块（训练脚本核心）一起下载。 - 进入目录：
cd kohya_ss。 - Windows 运行
gui-uv.bat，Linux 运行./gui-uv.sh。 脚本会自动装uv并拉依赖，首次会慢，等它跑完。
版本判断和子模块更新逻辑都在 setup/setup_common.py；两种方式细节见 docs/Installation/uv_windows.md 和 docs/Installation/uv_linux.md。
👉 卡在这一步？
- 症状：日志提示 "Git command not found"。原因：Git 没装或不在 PATH。处理：装 Git 并加入 PATH，重跑脚本。
- 症状：报错 "Invalid path: contains spaces"。原因：安装路径含空格。处理：把仓库移到无空格路径，删掉 venv 文件夹，重跑安装。
阶段三：启动验证
目标：确认 GUI 能在浏览器打开，且 PyTorch 识别到了显卡。
- 脚本跑完会自动打开浏览器，默认端口 7860。 看到 Kohya_ss 界面即启动成功。
- 没自动开？手动访问
http://127.0.0.1:7860。 远程或 SSH 场景加--headless启动，避免文件选择框卡死进程。 - 看启动日志里 "Torch detected GPU" 那一行，确认显卡被识别。 备选：跑
python -c "import torch;print(torch.cuda.is_available())"看是否返回 True。
👉 卡在这一步？
- 症状：日志提示 "Requirements installation failed"。原因：依赖批量装失败，多半是网络。处理：检查网络或换镜像后重跑；仍不行就改用 pip 方式。
- 症状：日志提示 "Torch reports GPU not available"。原因：PyTorch 与 CUDA 版本不匹配。处理：按 CUDA 12.8 重装对应版本的 PyTorch。
阶段四：高频报错补救
目标：把剩下几个真实高频问题一次说清。
- 启动报 "No module named tkinter"：说明缺 Tk 图形组件。 重装 Python 并勾选 tcl/tk；Ubuntu 用
sudo apt install python3-tk。 - 训练时报页面文件（Page File）错误：说明 Windows 内存上限不够。 去系统设置里调大页面文件大小上限。
- V100 上 GPU 利用率偏低：不是装坏了，是优化器没配对。 换 adamW8bit 优化器并调大 batch_size，详见 docs/troubleshooting_tesla_v100.md。
- 提示 "Modules installed outside the virtual environment"：说明虚拟环境外混装了包。 按 setup/check_local_modules.py 打印的清理命令处理。
排障速查表
| 报错关键字 | 最可能原因 | 处理动作 |
|---|---|---|
| must be >= 3.10.9 and < 3.13.0 | Python 版本不在支持范围 | 改装 3.11.x |
| Invalid path: contains spaces | 安装路径含空格 | 移到无空格路径，删 venv 重跑 |
| No module named tkinter | 缺 Tk 组件 | 重装 Python 勾选 tcl/tk，或装 python3-tk |
| Git command not found | Git 未装或不在 PATH | 装 Git 加 PATH，重跑 |
| Requirements installation failed | 依赖批量安装失败 | 查网络/换镜像，或改 pip 方式 |
| Torch reports GPU not available | PyTorch 与 CUDA 不匹配 | 按 CUDA 12.8 重装 PyTorch |
| Page file 相关 X 错误 | Windows 页面文件上限不足 | 调大页面文件大小 |
| outside the virtual environment | 环境外混装模块 | 按提示清理或重装环境 |
替代方案
本地装不动时，可以走云端，省去装环境的麻烦。
- Runpod：用模板起现成 GPU 训练环境，见 docs/installation_runpod.md。
- Docker：容器化部署，环境一致性好，适合开发者，见 docs/installation_docker.md。
收尾检查清单
python --version落在 3.10.9～3.12.xnvidia-smi能识别显卡，CUDA 12.8- 安装路径无空格、无中文
- 浏览器能打开 7860 端口的 GUI
- 启动日志出现 "Torch detected GPU"
下一步：训练参数和 LoRA 选项看 docs/LoRA/top_level.md。装好后先拿一小批图片试跑一次，再放大正式训练。遇到新报错，先搜日志里的关键字，再对照本表处理。
【免费下载链接】kohya_ss项目地址: https://gitcode.com/GitHub_Trending/ko/kohya_ss
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
