1580158
/
kohya_ss
mirror of https://github.com/bmaltais/kohya_ss
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: extract pip/uv installation guides to OS-specific markdown files and update main README

pull/3287/head
Adam Nielsen 2025-06-15 23:09:56 +02:00
parent c083029023
commit 57ec255a1f
5 changed files with 642 additions and 371 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

447
README.md
View File

@ -5,7 +5,11 @@
[![License](https://img.shields.io/github/license/bmaltais/kohya_ss)](LICENSE.md)
[![GitHub issues](https://img.shields.io/github/issues/bmaltais/kohya_ss)](https://github.com/bmaltais/kohya_ss/issues)
This project provides a user-friendly Gradio-based Graphical User Interface (GUI) for [Kohya's Stable Diffusion training scripts](https://github.com/kohya-ss/sd-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).
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](https://github.com/kohya-ss/sd-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.
@ -16,390 +20,91 @@ Support for Linux and macOS is also available. While Linux support is actively m
## Table of Contents
- [Kohya's GUI](#kohyas-gui)
- [Table of Contents](#table-of-contents)
- [🦒 Colab](#-colab)
- [Installation](#installation)
- [Prerequisites](#prerequisites)
- [Installing Prerequisites on Windows](#installing-prerequisites-on-windows)
- [Installing Prerequisites on Linux--macos](#installing-prerequisites-on-linux--macos)
- [Cloning the Repository](#cloning-the-repository)
- [Installation Methods](#installation-methods)
- [Using `uv` (Recommended)](#using-uv-recommended)
- [For Windows](#for-windows)
- [For Linux](#for-linux)
- [Using `pip` (Traditional Method)](#using-pip-traditional-method)
- [Using `pip` For Windows](#using-pip-for-windows)
- [Using `pip` For Linux and macOS](#using-pip-for-linux-and-macos)
- [Using `conda`](#using-conda)
- [Optional: Install Location Details](#optional-install-location-details)
- [Runpod](#runpod)
- [Novita](#novita)
- [Docker](#docker)
- [Upgrading](#upgrading)
- [Windows Upgrade](#windows-upgrade)
- [Linux and macOS Upgrade](#linux-and-macos-upgrade)
- [Starting GUI Service](#starting-gui-service)
- [Launching the GUI on Windows (pip method)](#launching-the-gui-on-windows-pip-method)
- [Launching the GUI on Windows (uv method)](#launching-the-gui-on-windows-uv-method)
- [Launching the GUI on Linux and macOS](#launching-the-gui-on-linux-and-macos)
- [Launching the GUI on Linux (uv method)](#launching-the-gui-on-linux-uv-method)
- [Custom Path Defaults](#custom-path-defaults)
- [LoRA](#lora)
- [Installation Options](#installation-options)
- [Local Installation Overview](#local-installation-overview)
- [`uv` vs `pip` – What's the Difference?](#uv-vs-pip--whats-the-difference)
- [Cloud Installation Overview](#cloud-installation-overview)
- [Colab](#-colab)
- [Runpod, Novita, Docker](#runpod-novita-docker)
- [Custom Path Defaults](#custom-path-defaults)
- [LoRA](#lora)
- [Sample image generation during training](#sample-image-generation-during-training)
- [Troubleshooting](#troubleshooting)
- [Page File Limit](#page-file-limit)
- [No module called tkinter](#no-module-called-tkinter)
- [LORA Training on TESLA V100 - GPU Utilization Issue](#lora-training-on-tesla-v100---gpu-utilization-issue)
- [SDXL training](#sdxl-training)
- [Masked loss](#masked-loss)
- [Guides](#guides)
- [Using Accelerate Lora Tab to Select GPU ID](#using-accelerate-lora-tab-to-select-gpu-id)
- [Starting Accelerate in GUI](#starting-accelerate-in-gui)
- [Running Multiple Instances (linux)](#running-multiple-instances-linux)
- [Monitoring Processes](#monitoring-processes)
- [Interesting Forks](#interesting-forks)
- [Contributing](#contributing)
- [License](#license)
- [Change History](#change-history)
- [v25.0.3](#v2503)
- [v25.0.2](#v2502)
- [v25.0.1](#v2501)
- [v25.0.0](#v2500)
## 🦒 Colab
- [Page File Limit](#page-file-limit)
- [No module called tkinter](#no-module-called-tkinter)
- [LORA Training on TESLA V100 - GPU Utilization Issue](#lora-training-on-tesla-v100---gpu-utilization-issue)
- [SDXL training](#sdxl-training)
- [Masked loss](#masked-loss)
- [Guides](#guides)
- [Using Accelerate Lora Tab to Select GPU ID](#using-accelerate-lora-tab-to-select-gpu-id)
- [Starting Accelerate in GUI](#starting-accelerate-in-gui)
- [Running Multiple Instances (linux)](#running-multiple-instances-linux)
- [Monitoring Processes](#monitoring-processes)
- [Interesting Forks](#interesting-forks)
- [Contributing](#contributing)
- [License](#license)
- [Change History](#change-history)
- [v25.0.3](#v2503)
- [v25.0.2](#v2502)
- [v25.0.1](#v2501)
- [v25.0.0](#v2500)
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.
## Installation Options
You can run `kohya_ss` either **locally on your machine** or via **cloud-based solutions** like Colab or Runpod.
- If you have a GPU-equipped PC and want full control: install it locally using `uv` or `pip`.
- If your system doesn’t meet requirements or you prefer a browser-based setup: use Colab or a paid GPU provider like Runpod or Novita.
- If you are a developer or DevOps user, Docker is also supported.
---
### 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](./docs/Installation/uv_linux.md) |
| Linux or Mac | `pip` | [pip_linux.md](./docs/Installation/pip_linux.md) |
| Windows | `uv` | [uv_windows.md](./docs/Installation/uv_windows.md) |
| Windows | `pip` | [pip_windows.md](./docs/Installation/pip_windows.md) |
#### `uv` vs `pip` – What's the Difference?
- `uv` is faster and isolates dependencies more cleanly, ideal if you want minimal setup hassle.
- `pip` is more traditional, easier to debug if issues arise, and works better with some IDEs or Python tooling.
- If unsure: try `uv`. If it doesn't work for you, fall back to `pip`.
### Cloud Installation Overview
#### 🦒 Colab
For browser-based training without local setup, use this Colab notebook:
<https://github.com/camenduru/kohya_ss-colab>
- No installation required
- Free to use (GPU availability may vary)
- Maintained by **camenduru**, not the original author
| Colab | Info |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ |
| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/camenduru/kohya_ss-colab/blob/main/kohya_ss_colab.ipynb) | kohya_ss_gui_colab |
## Installation
> 💡 If you encounter issues, please report them on camenduru’s repo.
### Prerequisites
**Special thanks**
I would like to express my gratitude to camenduru for their valuable contribution.
Before you begin, make sure your system meets the following minimum requirements:
#### Runpod, Novita, Docker
- **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
These options are for users running training on hosted GPU infrastructure or containers.
#### Installing Prerequisites on Windows
- **[Runpod setup](docs/runpod_setup.md)** – Ready-made GPU background training via templates.
- **[Novita setup](docs/novita_setup.md)** – Similar to Runpod, but integrated into the Novita UI.
- **[Docker setup](docs/docker.md)** – For developers/sysadmins using containerized environments.
1. Install [Python 3.11.9](https://www.python.org/ftp/python/3.11.9/python-3.11.9-amd64.exe)
✅ Enable the "Add to PATH" option during setup
2. Install [CUDA 12.8 Toolkit](https://developer.nvidia.com/cuda-12-8-0-download-archive?target_os=Windows&target_arch=x86_64)
3. Install [Git](https://git-scm.com/download/win)
4. Install [Visual Studio Redistributables](https://aka.ms/vs/17/release/vc_redist.x64.exe)
#### 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:
```bash
sudo apt update
sudo apt install python3.10 python3.10-venv
```
2. Install [CUDA 12.8 Toolkit](https://developer.nvidia.com/cuda-12-8-0-download-archive?target_os=Linux&target_arch=x86_64)
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**:
```bash
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:
```powershell
gui-uv.bat
```
For full details and command-line options, see:
[Launching the GUI on Windows (uv method)](https://github.com/bmaltais/kohya_ss#launching-the-gui-on-windows-uv-method)
##### For Linux
Run:
```bash
./gui-uv.sh
```
For full details, including headless mode, see:
[Launching the GUI on Linux (uv method)](https://github.com/bmaltais/kohya_ss#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:
```shell
.\setup.bat
```
For systems with only more than one python release installed:
```shell
.\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:
```shell
chmod +x ./setup.sh
```
Run the setup script by executing the following command:
```shell
./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`
```shell
# 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](docs/installation_runpod.md) for details.
#### Novita
See [Novita Installation Guide](docs/installation_novita.md) for details.
#### Docker
See [Docker Installation Guide](docs/installation_docker.md) 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:
```powershell
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:
```powershell
git pull
```
2. Run the setup script to update dependencies:
```powershell
.\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:
```bash
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:
```bash
git pull
```
3. Refresh and update everything by running the setup script:
```bash
./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.
```text
--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:
```powershell
gui.ps1 --listen 127.0.0.1 --server_port 7860 --inbrowser --share
```
or
```powershell
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](https://astral.sh/uv) before running `gui-uv.bat` again.
```cmd
.\gui-uv.bat
```
or
```powershell
.\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:
```bash
./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](https://astral.sh/uv) before running `gui-uv.sh` again.
```shell
./gui-uv.sh --listen 127.0.0.1 --server_port 7860 --inbrowser --share
```
If you are running on a headless server, use:
```shell
./gui-uv.sh --headless --listen 127.0.0.1 --server_port 7860 --inbrowser --share
```
This script utilizes the `uv` managed environment.
## Custom Path Defaults

161
docs/Installation/pip_linux.md Normal file
View File

@ -0,0 +1,161 @@
# Linux – Installation (pip method)
Use this method if you prefer `pip` or are on macOS.
## Table of Contents
- [Prerequisites](#prerequisites)
- [Installation Steps](#installation-steps)
- [Using Conda](#using-conda-optional)
- [Clone the Repository](#clone-the-repository)
- [Run the Setup Script](#run-the-setup-script)
- [Start the GUI](#start-the-gui)
- [Available CLI Options](#available-cli-options)
- [Upgrade Instructions](#upgrade-instructions)
- [Optional: Install Location Details](#optional-install-location-details)
## Prerequisites
- **Python 3.10.9** (or higher, but below 3.11)
- **Git** – Required for cloning the repository
- **NVIDIA CUDA Toolkit 12.8**
- **NVIDIA GPU** – Required for training; VRAM needs vary
- **(Optional) NVIDIA cuDNN** – Improves training speed and batch size
## Installation Steps
1. Install Python and Git. On Ubuntu 22.04 or later:
```bash
sudo apt update
sudo apt install python3.10 python3.10-venv git
```
2. Install [CUDA 12.8 Toolkit](https://developer.nvidia.com/cuda-12-8-0-download-archive?target_os=Linux&target_arch=x86_64)
Follow the instructions for your distribution.
3.
> [!NOTE]
> CUDA is usually not required and may not be compatible with Apple Silicon GPUs.
### Using `conda`
If you prefer Conda over `venv`, you can create an environment like this:
```shell
# 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
```
## Clone the Repository
Clone with submodules:
```bash
git clone --recursive https://github.com/bmaltais/kohya_ss.git
cd kohya_ss
```
## Run the Setup Script
Make the setup script executable:
```bash
chmod +x setup.sh
```
Run:
```bash
./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.
## Start the GUI
Start with:
```bash
./gui.sh --listen 127.0.0.1 --server_port 7860 --inbrowser --share
```
You can also run `kohya_gui.py` directly with the same flags.
For help:
```bash
./gui.sh --help
```
This method uses a standard Python virtual environment.
### Available CLI Options
You can pass the following arguments to `gui.sh` or `kohya_gui.py`:
```text
--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
```
## Upgrade Instructions
To upgrade, pull the latest changes and rerun setup:
```bash
git pull
./setup.sh
```
## Optional: Install Location Details
On Linux, the setup script will install in the current directory if possible.
If that fails:
- Fallback: `/opt/kohya_ss`
- If not writable: `$HOME/kohya_ss`
- If all fail: stays in the current directory
To override the location, use:
```bash
./setup.sh -d /your/custom/path
```
On macOS, the behavior is similar but defaults to `$HOME/kohya_ss`.
If you use interactive mode, the default Accelerate values are:
- Machine: `This machine`
- Compute: `None`
- Others: `No`

168
docs/Installation/pip_windows.md Normal file
View File

@ -0,0 +1,168 @@
# Windows – Installation (pip method)
Use this method if `uv` is not available or you prefer the traditional approach.
## Table of Contents
- [Prerequisites](#prerequisites)
- [Installation Steps](#installation-steps)
- [Using Conda](#using-conda-optional)
- [Clone the Repository](#clone-the-repository)
- [Run the Setup Script](#run-the-setup-script)
- [Start the GUI](#start-the-gui)
- [Available CLI Options](#available-cli-options)
- [Upgrade Instructions](#upgrade-instructions)
- [Optional: Install Location Details](#optional-install-location-details)
## Prerequisites
- **Python 3.10.11**
- **Git** – Required for cloning the repository
- **NVIDIA CUDA Toolkit 12.8**
- **NVIDIA GPU** – Required for training; VRAM needs vary
- **(Optional) NVIDIA cuDNN** – Improves training speed and batch size
- (Optional) Visual Studio Redistributables: [vc_redist.x64.exe](https://aka.ms/vs/17/release/vc_redist.x64.exe)
## Installation Steps
1. Install [Python 3.11.9](https://www.python.org/ftp/python/3.11.9/python-3.11.9-amd64.exe)
✅ Enable the "Add to PATH" option during setup
2. Install [CUDA 12.8 Toolkit](https://developer.nvidia.com/cuda-12-8-0-download-archive?target_os=Windows&target_arch=x86_64)
3. Install [Git](https://git-scm.com/download/win)
4. Install [Visual Studio Redistributables](https://aka.ms/vs/17/release/vc_redist.x64.exe)
## Using Conda (Optional)
If you prefer Conda over `venv`, you can create an environment like this:
```powershell
conda create -n kohyass python=3.10
conda activate kohyass
setup.bat
```
You can also use:
```powershell
setup-3.10.bat
```
Then run:
```powershell
gui.ps1
```
or:
```cmd
gui.bat
```
## Clone the Repository
Clone with submodules:
```cmd
git clone --recursive https://github.com/bmaltais/kohya_ss.git
cd kohya_ss
```
> The `--recursive` flag ensures all submodules are fetched.
## Run the Setup Script
Run:
```cmd
setup.bat
```
If you have multiple Python versions installed:
```cmd
setup-3.10.bat
```
During the Accelerate configuration step, use the default values as proposed 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*
These optional steps improve training speed for NVIDIA 30X0/40X0 GPUs. They allow for larger batch sizes and faster training.
Run:
```cmd
setup.bat
```
Then select:
```
2. (Optional) Install cudnn files (if you want to use the latest supported cudnn version)
```
## Start the GUI
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:
```powershell
gui.ps1 --listen 127.0.0.1 --server_port 7860 --inbrowser --share
```
or
```cmd
gui.bat --listen 127.0.0.1 --server_port 7860 --inbrowser --share
```
You can also run `kohya_gui.py` directly with the same flags.
For help:
```cmd
gui.bat --help
```
This method uses a Python virtual environment managed via pip.
### Available CLI Options
```text
--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
```
## Upgrade Instructions
To upgrade your environment:
```cmd
git pull
setup.bat
```

138
docs/Installation/uv_linux.md Normal file
View File

@ -0,0 +1,138 @@
# Linux – Installation (uv method)
Recommended setup for most Linux users.
If you have macOS please use **pip method**.
## Table of Contents
- [Prerequisites](#prerequisites)
- [Installation Steps](#installation-steps)
- [Clone the Repository](#clone-the-repository)
- [Start the GUI](#start-the-gui)
- [Available CLI Options](#available-cli-options)
- [Upgrade Instructions](#upgrade-instructions)
- [Optional: Install Location Details](#optional-install-location-details)
## Prerequisites
- **Python 3.10.9** (or higher, but below 3.11)
- **Git** – Required for cloning the repository
- **NVIDIA CUDA Toolkit 12.8**
- **NVIDIA GPU** – Required for training; VRAM needs vary
- **(Optional) NVIDIA cuDNN** – Improves training speed and batch size
## Installation Steps
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:
```bash
sudo apt update
sudo apt install python3.10 python3.10-venv git
```
2. Install [CUDA 12.8 Toolkit](https://developer.nvidia.com/cuda-12-8-0-download-archive?target_os=Linux&target_arch=x86_64)
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.
## Clone the Repository
To install the project, you must first clone the repository **with submodules**:
```bash
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.
Run:
```bash
./gui-uv.sh
```
## Start the GUI
To launch the GUI service, run `./gui-uv.sh` or run the `kohya_gui.py` script directly. Use the command line arguments listed below to configure the underlying service.
### Available CLI Options
```text
--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
```
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](https://astral.sh/uv) before running `gui-uv.sh` again.
```shell
./gui-uv.sh --listen 127.0.0.1 --server_port 7860 --inbrowser --share
```
If you are running on a headless server, use:
```shell
./gui-uv.sh --headless --listen 127.0.0.1 --server_port 7860 --inbrowser --share
```
This script utilizes the `uv` managed environment.
## Upgrade Instructions
To upgrade your installation to a new version, follow the instructions below.
1. Open a terminal and navigate to the root directory of the project.
2. Pull the latest changes from the repository:
```bash
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.
## Optional: Install Location Details
On Linux, the setup script will install in the current directory if possible.
If that fails:
- Fallback: `/opt/kohya_ss`
- If not writable: `$HOME/kohya_ss`
- If all fail: stays in the current directory
To override the location, use:
```bash
./setup.sh -d /your/custom/path
```
On macOS, the behavior is similar but defaults to `$HOME/kohya_ss`.
If you use interactive mode, the default Accelerate values are:
- Machine: `This machine`
- Compute: `None`
- Others: `No`

99
docs/Installation/uv_windows.md Normal file
View File

@ -0,0 +1,99 @@
# Windows – Installation (uv method)
Recommended for most Windows users.
## Table of Contents
- [Prerequisites](#prerequisites)
- [Installation Steps](#installation-steps)
- [Clone the Repository](#clone-the-repository)
- [Start the GUI](#start-the-gui)
- [Available CLI Options](#available-cli-options)
- [Upgrade Instructions](#upgrade-instructions)
-
## Prerequisites
- [Python 3.11.9](https://www.python.org/ftp/python/3.11.9/python-3.11.9-amd64.exe) – enable "Add to PATH"
- [Git for Windows](https://git-scm.com/download/win)
- [CUDA Toolkit 12.8](https://developer.nvidia.com/cuda-12-8-0-download-archive?target_os=Windows&target_arch=x86_64)
- **NVIDIA GPU** – Required for training; VRAM needs vary
- **(Optional) NVIDIA cuDNN** – Improves training speed and batch size
- (Optional) Visual Studio Redistributables: [vc_redist.x64.exe](https://aka.ms/vs/17/release/vc_redist.x64.exe)
## Installation Steps
1. Install [Python 3.11.9](https://www.python.org/ftp/python/3.11.9/python-3.11.9-amd64.exe)
✅ Enable the "Add to PATH" option during setup
2. Install [CUDA 12.8 Toolkit](https://developer.nvidia.com/cuda-12-8-0-download-archive?target_os=Windows&target_arch=x86_64)
3. Install [Git](https://git-scm.com/download/win)
4. Install [Visual Studio Redistributables](https://aka.ms/vs/17/release/vc_redist.x64.exe)
## Clone the Repository
Clone with submodules:
```powershell
git clone --recursive https://github.com/bmaltais/kohya_ss.git
cd kohya_ss
```
## Start the GUI
To launch the GUI, run:
```cmd
.\gui-uv.bat
```
If `uv` is not installed, the script will prompt you:
- Press `Y` to install `uv` automatically
- Or press `N` to cancel and install `uv` manually from [https://astral.sh/uv](https://astral.sh/uv)
Once installed, you can also start the GUI with additional flags:
```cmd
.\gui-uv.bat --listen 127.0.0.1 --server_port 7860 --inbrowser --share
```
This script utilizes the `uv` managed environment and handles dependencies and updates automatically.
### Available CLI Options
```text
--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
```
This script utilizes the `uv` managed environment and automatically handles dependencies and updates.
## Upgrade Instructions
1. Pull the latest changes:
```powershell
git pull
```
2. Run `gui-uv.bat` again. It will update the environment automatically.