Kohya's GUI

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:

• Easy-to-use interface for setting a wide range of training parameters.
• Automatic generation of the command-line interface (CLI) commands required to run the training scripts.
• Support for various training methods, including LoRA, Dreambooth, fine-tuning, and SDXL training.

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

Table of Contents

• Kohya's GUI
  • Table of Contents
  • 🦒 Colab
  • Installation
    • Prerequisites
      • Installing Prerequisites on Windows
      • Installing Prerequisites on Linux--macos
    • Cloning the Repository
    • Installation Methods
      • Using uv (Recommended)
        • For Windows
        • For Linux
      • Using pip (Traditional Method)
        • Using pip For Windows
        • Using pip For Linux and macOS
      • Using conda
    • Optional: Install Location Details
    • Runpod
    • Novita
    • Docker
  • Upgrading
    • Windows Upgrade
    • Linux and macOS Upgrade
  • Starting GUI Service
    • Launching the GUI on Windows (pip method)
    • Launching the GUI on Windows (uv method)
    • Launching the GUI on Linux and macOS
    • Launching the GUI on Linux (uv method)
  • Custom Path Defaults
  • LoRA
  • Sample image generation during training
  • Troubleshooting
    • Page File Limit
    • No module called tkinter
    • LORA Training on TESLA V100 - GPU Utilization Issue
  • SDXL training
  • Masked loss
  • Guides
    • Using Accelerate Lora Tab to Select GPU ID
      • Starting Accelerate in GUI
      • Running Multiple Instances (linux)
      • Monitoring Processes
  • Interesting Forks
  • Contributing
  • License
  • Change History
    • v25.0.3
    • v25.0.2
    • v25.0.1
    • v25.0.0

🦒 Colab

This Colab notebook was not created or maintained by me; however, it appears to function effectively. The source can be found at: https://github.com/camenduru/kohya_ss-colab.

I would like to express my gratitude to camenduru for their valuable contribution. If you encounter any issues with the Colab notebook, please report them on their repository.

Colab	Info
	kohya_ss_gui_colab

Installation

Prerequisites

Before you begin, make sure your system meets the following minimum requirements:

• Python
  • Windows: Version 3.11.9
  • Linux/macOS: Version 3.10.9 or higher, but below 3.11.0
• Git – Required for cloning the repository
• NVIDIA CUDA Toolkit – Version 12.8 or compatible
• NVIDIA GPU – Required for training; VRAM needs vary
• (Optional) NVIDIA cuDNN – Improves training speed and batch size
• Windows only – Visual Studio 2015–2022 Redistributables

Installing Prerequisites on Windows

1. Install Python 3.11.9
   ✅ Enable the "Add to PATH" option during setup

2. Install CUDA 12.8 Toolkit

3. Install Git

4. Install Visual Studio Redistributables

Installing Prerequisites on Linux / macOS

1. Install Python (Make sure you have Python version 3.10.9 or higher (but lower than 3.11.0) installed on your system.) On Ubuntu 22.04 or later:

   sudo apt update
   sudo apt install python3.10 python3.10-venv

2. Install CUDA 12.8 Toolkit
   Follow the instructions for your distribution.

Note

macOS is only supported via the pip method.
CUDA is usually not required and may not be compatible with Apple Silicon GPUs.

Cloning the Repository

To install the project, you must first clone the repository with submodules:

git clone --recursive https://github.com/bmaltais/kohya_ss.git
cd kohya_ss

The --recursive flag ensures that all required Git submodules are also cloned.

---

Installation Methods

This project offers two primary methods for installing and running the GUI: using the uv package manager (recommended for ease of use and automatic updates) or using the traditional pip package manager. Below, you'll find details on both approaches. Please read this section to decide which method best suits your needs before proceeding to the OS-specific installation prerequisites.

Key Differences:

• uv method:
  • Simplifies the setup process.
  • Automatically handles updates when you run gui-uv.bat (Windows) or gui-uv.sh (Linux).
  • No need to run setup.bat or setup.sh after the initial clone.
  • This is the recommended method for most users on Windows and Linux.
  • Not recommended for Runpod or macOS installations. For these, please use the pip method.
• pip method:
  • The traditional method, requiring manual execution of setup.bat (Windows) or setup.sh (Linux) after cloning and for updates.
  • Necessary for environments like Runpod and macOS where the uv scripts are not intended to be used.

Subsequent sections will detail the specific commands for each method.

Using uv (Recommended)

Note

This method is not intended for runpod or MacOS installation. Use the "pip based package manager" setup instead.

For Windows

Run:

gui-uv.bat

For full details and command-line options, see:
Launching the GUI on Windows (uv method)

For Linux

Run:

./gui-uv.sh

For full details, including headless mode, see:
Launching the GUI on Linux (uv method)

Using pip (Traditional Method)

This method uses the traditional pip package manager and requires manual script execution for setup and updates. It is necessary for environments like Runpod or macOS, or if you prefer managing your environment with pip.

Using pip For Windows

For systems with only python 3.10.11 installed:

.\setup.bat

For systems with only more than one python release installed:

.\setup-3.10.bat

During the accelerate config step, use the default values as proposed during the configuration unless you know your hardware demands otherwise. The amount of VRAM on your GPU does not impact the values used.

• Optional: CUDNN 8.9.6.50

  The following steps are optional but will improve the learning speed for owners of NVIDIA 30X0/40X0 GPUs. These steps enable larger training batch sizes and faster training speeds.

  Run .\setup.bat and select 2. (Optional) Install cudnn files (if you want to use the latest supported cudnn version).

Using pip For Linux and macOS

If you encounter permission issues, make the setup.sh script executable by running the following command:

chmod +x ./setup.sh

Run the setup script by executing the following command:

./setup.sh

Note

If you need additional options or information about the runpod environment, you can use setup.sh -h or setup.sh --help to display the help message.

Using conda

# Create Conda Environment
conda create -n kohyass python=3.11
conda activate kohyass

# Run the Scripts
chmod +x setup.sh
./setup.sh

chmod +x gui.sh
./gui.sh

Note

For Windows users, the chmod +x commands are not necessary. You should run setup.bat and subsequently gui.bat (or gui.ps1 if you prefer PowerShell) instead of the .sh scripts.

Optional: Install Location Details for Linux and Mac

Note: The information below regarding install location applies to both uv and pip installation methods. Most users don’t need to change the install directory. The following applies only if you want to customize the installation path or troubleshoot permission issues.

The default installation location on Linux is the directory where the script is located. If a previous installation is detected in that location, the setup will proceed there. Otherwise, the installation will fall back to /opt/kohya_ss. If /opt is not writable, the fallback location will be $HOME/kohya_ss. Finally, if none of the previous options are viable, the installation will be performed in the current directory.

For macOS and other non-Linux systems, the installation process will attempt to detect the previous installation directory based on where the script is run. If a previous installation is not found, the default location will be $HOME/kohya_ss. You can override this behavior by specifying a custom installation directory using the -d or --dir option when running the setup script.

If you choose to use the interactive mode, the default values for the accelerate configuration screen will be "This machine," "None," and "No" for the remaining questions. These default answers are the same as the Windows installation.

Runpod

See Runpod Installation Guide for details.

Novita

See Novita Installation Guide for details.

Docker

See Docker Installation Guide for details.

Upgrading

To upgrade your installation to a new version, follow the instructions below.

Windows Upgrade

If a new release becomes available, you can upgrade your repository by following these steps:

• If you are using the uv-based installation (gui-uv.bat):

  1. Pull the latest changes from the repository:

     git pull

  2. Updates to the Python environment are handled automatically when you next run the gui-uv.bat script. No separate setup script execution is needed.

• If you are using the pip-based installation (gui.bat or gui.ps1):

  1. Pull the latest changes from the repository:

     git pull

  2. Run the setup script to update dependencies:

     .\setup.bat

Linux and macOS Upgrade

To upgrade your installation on Linux or macOS, follow these steps:

• If you are using the uv-based installation (gui-uv.sh):

  1. Open a terminal and navigate to the root directory of the project.
  2. Pull the latest changes from the repository:

     git pull

  3. Updates to the Python environment are handled automatically when you next run the gui-uv.sh script. No separate setup script execution is needed.

• If you are using the pip-based installation (gui.sh):

  1. Open a terminal and navigate to the root directory of the project.
  2. Pull the latest changes from the repository:

     git pull

  3. Refresh and update everything by running the setup script:

     ./setup.sh

Starting GUI Service

To launch the GUI service, use the script corresponding to your chosen installation method (uv or pip), or run the kohya_gui.py script directly. Use the command line arguments listed below to configure the underlying service.

  --help                show this help message and exit
  --config CONFIG       Path to the toml config file for interface defaults
  --debug               Debug on
  --listen LISTEN       IP to listen on for connections to Gradio
  --username USERNAME   Username for authentication
  --password PASSWORD   Password for authentication
  --server_port SERVER_PORT
                        Port to run the server listener on
  --inbrowser           Open in browser
  --share               Share the gradio UI
  --headless            Is the server headless
  --language LANGUAGE   Set custom language
  --use-ipex            Use IPEX environment
  --use-rocm            Use ROCm environment
  --do_not_use_shell    Enforce not to use shell=True when running external commands
  --do_not_share        Do not share the gradio UI
  --requirements REQUIREMENTS
                        requirements file to use for validation
  --root_path ROOT_PATH
                        `root_path` for Gradio to enable reverse proxy support. e.g. /kohya_ss
  --noverify            Disable requirements verification

Launching the GUI on Windows (pip method)

If you installed using the pip method, use either the gui.ps1 or gui.bat script located in the root directory. Choose the script that suits your preference and run it in a terminal, providing the desired command line arguments. Here's an example:

gui.ps1 --listen 127.0.0.1 --server_port 7860 --inbrowser --share

or

gui.bat --listen 127.0.0.1 --server_port 7860 --inbrowser --share

Launching the GUI on Windows (uv method)

If you installed using the uv method, use the gui-uv.bat script to start the GUI. Follow these steps:

When you run gui-uv.bat, it will first check if uv is installed on your system. If uv is not found, the script will prompt you, asking if you'd like to attempt an automatic installation. You can choose 'Y' to let the script try to install uv for you, or 'N' to cancel. If you cancel, you'll need to install uv manually from https://astral.sh/uv before running gui-uv.bat again.

.\gui-uv.bat

or

.\gui-uv.bat --listen 127.0.0.1 --server_port 7860 --inbrowser --share

This script utilizes the uv managed environment.

Launching the GUI on Linux and macOS

If you installed using the pip method on Linux or macOS, run the gui.sh script located in the root directory. Provide the desired command line arguments as follows:

./gui.sh --listen 127.0.0.1 --server_port 7860 --inbrowser --share

Launching the GUI on Linux (uv method)

If you installed using the uv method on Linux, use the gui-uv.sh script to start the GUI. Follow these steps:

When you run gui-uv.sh, it will first check if uv is installed on your system. If uv is not found, the script will prompt you, asking if you'd like to attempt an automatic installation. You can choose 'Y' (or 'y') to let the script try to install uv for you, or 'N' (or 'n') to cancel. If you cancel, you'll need to install uv manually from https://astral.sh/uv before running gui-uv.sh again.

./gui-uv.sh --listen 127.0.0.1 --server_port 7860 --inbrowser --share

If you are running on a headless server, use:

./gui-uv.sh --headless --listen 127.0.0.1 --server_port 7860 --inbrowser --share

This script utilizes the uv managed environment.

Custom Path Defaults

The repository now provides a default configuration file named config.toml. This file is a template that you can customize to suit your needs.

To use the default configuration file, follow these steps:

1. Copy the config example.toml file from the root directory of the repository to config.toml.
2. Open the config.toml file in a text editor.
3. Modify the paths and settings as per your requirements.

This approach allows you to easily adjust the configuration to suit your specific needs to open the desired default folders for each type of folder/file input supported in the GUI.

You can specify the path to your config.toml (or any other name you like) when running the GUI. For instance: ./gui.bat --config c:\my_config.toml

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:

• LoRA Training Guide
• LoRA Training Options

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:

• --n: Negative prompt up to the next option.
• --w: Specifies the width of the generated image.
• --h: Specifies the height of the generated image.
• --d: Specifies the seed of the generated image.
• --l: Specifies the CFG scale of the generated image.
• --s: Specifies the number of steps in the generation.

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

• Open the kohya GUI on your desired port.
• Open the Accelerate launch tab
• Ensure the Multi-GPU checkbox is unchecked.
• Set GPU IDs to the desired GPU (like 1).

Running Multiple Instances (linux)

• For tracking multiple processes, use separate kohya GUI instances on different ports (e.g., 7860, 7861).
• Start instances using nohup ./gui.sh --listen 0.0.0.0 --server_port <port> --headless > log.log 2>&1 &.

Monitoring Processes

• Open each GUI in a separate browser tab.
• For terminal access, use SSH and tools like tmux or screen.

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:

• For bug reports or feature requests, please open an issue on the GitHub Issues page.
• If you'd like to submit code changes, please open a pull request. Ensure your changes are well-tested and follow the existing code style.
• For security-related concerns, please refer to our SECURITY.md file.

License

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

Change History

v25.0.3

• Upgrade Gradio, diffusers and huggingface-hub to latest release to fix issue with ASGI.
• Add a new method to setup and run the GUI. You will find two new script for both Windows (gui-uv.bat) and Linux (gui-uv.sh). With those scripts there is no need to run setup.bat or setup.sh anymore.

v25.0.2

• Force gradio to 5.14.0 or greater so it is updated.

v25.0.1

• Fix issue with requirements version causing huggingface download issues

v25.0.0

• Major update: Introduced support for flux.1 and sd3, moving the GUI to align with more recent script functionalities.
• Users preferring the pre-flux.1/sd3 version can check out tag v24.1.7.

  git checkout v24.1.7

• For details on new flux.1 and sd3 parameters, refer to the sd-scripts README.