kohya_ss README

The project's README from github.com/bmaltais/kohya_ss. As one markdown file: README.md.

Kohya's GUI

GitHub stars GitHub forks License GitHub issues

This is a GUI and CLI for training diffusion models.

This project provides a user-friendly Gradio-based Graphical User Interface (GUI) for Kohya's Stable Diffusion training scripts. Stable Diffusion training empowers users to customize image generation models by fine-tuning existing models, creating unique artistic styles, and training specialized models like LoRA (Low-Rank Adaptation).

Key features of this GUI include:

Support for Linux and macOS is also available. While Linux support is actively maintained through community contributions, macOS compatibility may vary.

Table of Contents

Installation Options

You can run kohya_ss either locally on your machine or via cloud-based solutions like Colab or Runpod.

Local Installation Overview

You can install kohya_ss locally using either the uv or pip method. Choose one depending on your platform and preferences:

Platform Recommended Method Instructions
Linux uv uv_linux.md
Linux or Mac pip pip_linux.md
Windows uv uv_windows.md
Windows pip pip_windows.md

uv vs pip – What's the Difference?

Cloud Installation Overview

🦒 Colab

For browser-based training without local setup, use this Colab notebook:
https://github.com/camenduru/kohya_ss-colab

Colab Info
Open In Colab kohya_ss_gui_colab

💡 If you encounter issues, please report them on camenduru’s repo.

Special thanks
I would like to express my gratitude to camenduru for their valuable contribution.

Runpod, Novita, Docker

These options are for users running training on hosted GPU infrastructure or containers.

Offline / air-gapped GUI shell

After a normal install, the local Gradio UI shell is intended to run without the browser (or server process) fetching third-party CDN hosts for core assets:

Layer Offline after install? Notes
GUI shell (HTML/JS/CSS, theme fonts, About tab) Yes No Google Fonts, cdnjs iframe-resizer, About remote badges, or Gradio analytics by default
Install (PyPI / torch wheels / uv sync) No One-time network (or a pre-populated cache / mirror) is still required
Captioning / HF models / W&B / HF upload Feature-dependent Needs local model caches or intentional network; for hard offline training set HF_HUB_OFFLINE=1 and TRANSFORMERS_OFFLINE=1

The public GitHub README.md may still use marketing badges; the in-app About → README view strips remote images so the browser does not load them.

Custom Path Defaults with config.toml

The GUI supports a configuration file named config.toml that allows you to set default paths for many of the input fields. This is useful for avoiding repetitive manual selection of directories every time you start the GUI.

Purpose of config.toml:

How to Use and Customize:

  1. Create your configuration file:
    • In the root directory of the kohya_ss repository, you'll find a file named config example.toml.
    • Copy this file and rename the copy to config.toml. This config.toml file will be automatically loaded when the GUI starts.
  2. Edit config.toml:
    • Open config.toml with a text editor.
    • The file uses TOML (Tom's Obvious, Minimal Language) format, which consists of key = "value" pairs.
    • Modify the paths for the keys according to your local directory structure.
    • Important:
      • Use absolute paths (e.g., C:/Users/YourName/StableDiffusion/Models or /home/yourname/sd-models).
      • Alternatively, you can use paths relative to the kohya_ss root directory.
      • Ensure you use forward slashes (/) for paths, even on Windows, as this is generally more compatible with TOML and Python.
      • Make sure the specified directories exist on your system.

Structure of config.toml:

The config.toml file can have several sections, typically corresponding to different training modes or general settings. Common keys you might want to set include:

Example Configurations:

Here's an example snippet of what your config.toml might look like:

# General settings
model_dir = "C:/ai_stuff/stable-diffusion-webui/models/Stable-diffusion"
lora_model_dir = "C:/ai_stuff/stable-diffusion-webui/models/Lora"
vae_dir = "C:/ai_stuff/stable-diffusion-webui/models/VAE"
output_dir = "C:/ai_stuff/kohya_ss_outputs"
logging_dir = "C:/ai_stuff/kohya_ss_outputs/logs"

# Dreambooth specific paths
db_model_dir = "C:/ai_stuff/stable-diffusion-webui/models/Stable-diffusion"
db_reg_image_dir = "C:/ai_stuff/datasets/dreambooth_regularization_images"
# Add other db_... paths as needed

# Finetune specific paths
ft_model_dir = "C:/ai_stuff/stable-diffusion-webui/models/Stable-diffusion"
# Add other ft_... paths as needed

# LoRA / LoCon specific paths
lc_model_dir = "C:/ai_stuff/stable-diffusion-webui/models/Stable-diffusion" # Base model for LoRA training
lc_output_dir = "C:/ai_stuff/kohya_ss_outputs/lora"
lc_dataset_dir = "C:/ai_stuff/datasets/my_lora_project"
# Add other lc_... paths as needed

# You can find a comprehensive list of all available keys in the `config example.toml` file.
# Refer to it to customize paths for all supported options in the GUI.

Using a Custom Config File Path:

If you prefer to name your configuration file differently or store it in another location, you can specify its path using the --config command-line argument when launching the GUI:

By effectively using config.toml, you can significantly speed up your training setup process. Always refer to the config example.toml for the most up-to-date list of configurable paths.

Server Options

The config.toml file can also be used to configure the Gradio server.

allowed_paths

The allowed_paths option allows you to specify a list of directories that the application can access. This is useful if you want to store your models, datasets, or other files on an external drive or in a location outside of the application's root directory.

Example:

[server]
allowed_paths = ["/mnt/external_drive/models", "/home/user/datasets"]

Remote / SSH: use --headless

When you run the GUI on a remote machine (SSH, Runpod, Docker, cloud GPU) and open it in a browser, start with --headless.

Without it, native OS dialogs (easygui overwrite confirmation, local file pickers) run on the server process. Over SSH there is usually no interactive display, so those prompts can block training indefinitely.

--headless does two things that matter for remote use:

Examples:

# Linux / macOS
./gui.sh --listen 0.0.0.0 --server_port 7860 --headless

# Windows
gui.bat --listen 0.0.0.0 --server_port 7860 --headless

If you start without --headless over SSH or without a display, the process logs a warning recommending --headless. There is no separate --skip_overwrite flag; use --headless for that behavior on train start.

LoRA

To train a LoRA, you can currently use the train_network.py code. You can create a LoRA network by using the all-in-one GUI.

Once you have created the LoRA network, you can generate images using auto1111 by installing this extension.

For more detailed information on LoRA training options and advanced configurations, please refer to our LoRA documentation:

Sample image generation during training

A prompt file might look like this, for example:

# prompt 1
masterpiece, best quality, (1girl), in white shirts, upper body, looking at viewer, simple background --n low quality, worst quality, bad anatomy, bad composition, poor, low effort --w 768 --h 768 --d 1 --l 7.5 --s 28

# prompt 2
masterpiece, best quality, 1boy, in business suit, standing at street, looking back --n (low quality, worst quality), bad anatomy, bad composition, poor, low effort --w 576 --h 832 --d 2 --l 5.5 --s 40

Lines beginning with # are comments. You can specify options for the generated image with options like --n after the prompt. The following options can be used:

The prompt weighting such as ( ) and [ ] is working.

Troubleshooting

If you encounter any issues, refer to the troubleshooting steps below.

Page File Limit

If you encounter an X error related to the page file, you may need to increase the page file size limit in Windows.

No module called tkinter

If you encounter an error indicating that the module tkinter is not found, try reinstalling Python 3.10 on your system.

LORA Training on TESLA V100 - GPU Utilization Issue

See Troubleshooting LORA Training on TESLA V100 for details.

SDXL training

For detailed guidance on SDXL training, please refer to the official sd-scripts documentation and relevant sections in our LoRA Training Guide.

Masked loss

The masked loss is supported in each training script. To enable the masked loss, specify the --masked_loss option.

[!WARNING] The feature is not fully tested, so there may be bugs. If you find any issues, please open an Issue.

ControlNet dataset is used to specify the mask. The mask images should be the RGB images. The pixel value 255 in R channel is treated as the mask (the loss is calculated only for the pixels with the mask), and 0 is treated as the non-mask. The pixel values 0-255 are converted to 0-1 (i.e., the pixel value 128 is treated as the half weight of the loss). See details for the dataset specification in the LLLite documentation.

Guides

The following are guides extracted from issues discussions

Using Accelerate Lora Tab to Select GPU ID

Starting Accelerate in GUI

Running Multiple Instances (linux)

Monitoring Processes

For more details, visit the GitHub issue.

Interesting Forks

To finetune HunyuanDiT models or create LoRAs, visit this fork

Contributing

Contributions are welcome! If you'd like to contribute to this project, please consider the following:

License

This project is licensed under the Apache License 2.0. See the LICENSE.md file for details.

Change History

Only the upcoming release is detailed here. For the full history of published releases, see GitHub Releases.

v26.0.0

Added

Changed

Fixed

kohya_ss (bmaltais/kohya_ss)

Searching Database…

12.6K ·GitHub
Kohya_ss
What is this?Kohya's GUI is a Gradio-based graphical interface (plus CLI) for Kohya's Stable Diffusion training scripts, letting you fine-tune diffusion models, train LoRA/LoHa/LoKr, Dreambooth, Textual Inversion, and full fine-tuning without hand-writing training commands.
Is this a GUI, a CLI, or both?It's primarily a browser-based Gradio GUI that automatically generates and runs the underlying CLI training commands for you, so you get both a point-and-click interface and the raw scripts underneath.
How do I get it running?Install it locally with uv or pip following platform-specific docs (uvlinux.md, piplinux.md, uvwindows.md, pipwindows.md), or skip local setup entirely and use the provided Colab notebook, Runpod/Novita templates, or Docker.
Any limitations I should know about, like masked loss or macOS support?Masked loss is supported but explicitly flagged as not fully tested and may have bugs; macOS support is community-maintained and compatibility can vary compared to the actively maintained Linux/Windows paths.
Does it only work on local machines, or can I run it remotely over SSH?It can run remotely (SSH, Runpod, Docker, cloud GPU), but you must start it with the --headless flag, since without a display, native overwrite-confirmation dialogs can block training indefinitely.
Can it run fully offline after installation?The GUI shell itself (HTML/JS/CSS, fonts) runs offline after install with no external CDN calls, but the initial install (PyPI/torch wheels) needs network access once, and features like captioning or Hugging Face model downloads need their own offline env vars (HF_HUB_OFFLINE, TRANSFORMERS_OFFLINE) to avoid network calls.
Which base Stable Diffusion models can I train with this?It supports SD 1.5/2.x, SDXL, SD3, Flux.1, Lumina Image 2.0, Anima, and HunyuanImage-2.1, in addition to LoRA/LoHa/LoKr, Dreambooth, fine-tuning, Textual Inversion, and LECO concept-erasure training.
What is config.toml for?It lets you pre-fill default directory paths (models, datasets, outputs, LoRA folders) so you don't have to manually browse to the same folders every time you launch the GUI.
How do I control which GPU gets used for training?Open the Accelerate Launch tab in the GUI, make sure Multi-GPU is unchecked, and set the GPU IDs field to the device you want (e.g. '1').
Can I generate preview images during training?Yes, by supplying a prompt file where each line can include options like --n (negative prompt), --w/--h (size), --d (seed), --l (CFG scale), and --s (steps), and prompt weighting with ( ) and [ ] is supported.
What are similar projects?ai-toolkit, stable-diffusion-webui-colab, stable-diffusion-webui-forge, InstantID, stable-diffusion, generative-models, Fooocus, unsloth
Which topics is it in?controlnet, colab, stable-diffusion, text-to-image, diffusion-models, lora, training, fine-tuning, image-generation, nvidia, generative-ai, huggingface
Creator
bmaltais
Size
24.8 MB
Stars
12.6K
Updated
CommitJul 10Releasev26.0.0Jul 09
Age
3y
Commits · 90 Days