How do I run Kohya_ss on a cloud GPU?

Cover: Run Kohya_ss on a cloud GPU, LoRA training GUI, --headless and an SSH tunnel

Clone bmaltais/kohya_ss with --recursive on a Raw GPU instance, start the GUI with ./gui-uv.sh --headless --listen 127.0.0.1 --server_port 7860, then open it on your own computer through an SSH tunnel at http://localhost:7860.

Updated 2026-10-29

This guide follows the official kohya_ss docs on GitHub (README, Linux uv install, Linux pip install), the uv installation docs and the Gradio sharing guide, all read on 2026-10-29. The latest kohya_ss release on GitHub that day was v26.0.0. It is for people who want to train LoRA, LoHa, LoKr, Dreambooth or Textual Inversion models in Kohya’s GUI on a rented NVIDIA GPU such as the RTX 5090 or the other cards listed on /pricing.

What is Kohya_ss?

According to its README, kohya_ss is a Gradio-based GUI and CLI for Kohya’s Stable Diffusion training scripts (sd-scripts). It builds the training command for you and supports LoRA, LoHa, LoKr, Dreambooth, fine-tuning and Textual Inversion. The README lists these base model families: Stable Diffusion 1.5/2.x, SDXL, SD3, Flux.1, Lumina Image 2.0, Anima and HunyuanImage-2.1. The project is licensed under the Apache License 2.0.

Item Official value (read 2026-10-29) Source
Recommended Linux install uv method (./gui-uv.sh) README, Installation Options
Python .python-version file: 3.11; pyproject.toml: >=3.10,<3.12 repo files
CUDA docs list NVIDIA CUDA Toolkit 12.8 as a prerequisite; PyTorch comes from the cu128 index uv_linux.md, pyproject.toml
GPU memory “VRAM needs vary” uv_linux.md
Remote use “always pass --headless” README, Remote / SSH
Default port in docs examples 7860 uv_linux.md, README

Step 1: Deploy a Raw GPU and connect

On /deploy, pick an NVIDIA GPU and the Raw GPU option (JupyterLab + CUDA pre-installed, root SSH on a dedicated container). Connect over SSH with the host, port and user shown for your instance, or open a terminal in JupyterLab.

VRAM need depends on model, precision and workflow; see How much VRAM do I need to run an LLM? for the general method and How much VRAM do I need for FLUX and SDXL? for image models. The install steps below are the same on every listed card.

Step 2: Check the environment first

nvidia-smi          # GPU name, driver version and the "CUDA Version" the driver supports
nvcc --version      # CUDA toolkit compiler, if installed
python3 --version
git --version
which curl uv tmux

The kohya_ss Linux docs list CUDA Toolkit 12.8 as a prerequisite, and its PyTorch packages come from the cu128 index, so look for a CUDA Version of 12.8 or higher in the nvidia-smi header. If it is lower, see How to install a specific PyTorch CUDA version on a cloud GPU before you train. If git, curl or tmux is missing, install it with the package manager (you are root on the container).

Step 3: Install uv and clone kohya_ss

The kohya_ss README recommends the uv method on Linux. Install uv with its official installer first, so gui-uv.sh does not have to ask:

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
uv --version

Then clone the repository with submodules, as the docs require:

cd ~
git clone --recursive https://github.com/bmaltais/kohya_ss.git
cd kohya_ss
cat .python-version

The uv method uses the Python version in the repo’s .python-version file, which pins 3.11; pyproject.toml requires Python >=3.10,<3.12 (both read 2026-10-29). According to the uv docs, uv downloads a Python version automatically if it cannot find it on the system, so you do not need to install Python 3.11 yourself for this route. If you skip the uv install above, gui-uv.sh asks whether to install uv for you; answer Y.

Step 4: Start the GUI in headless mode inside tmux

Start a tmux session so the GUI keeps running if your SSH connection drops, then launch it on the loopback address:

tmux new -s kohya
cd ~/kohya_ss
./gui-uv.sh --headless --listen 127.0.0.1 --server_port 7860

Detach with Ctrl-b then d; reattach later with tmux attach -t kohya. On the first run, gui-uv.sh updates the Git submodules and uv run installs the Python packages before the GUI starts, so wait until the log shows the local URL.

Why --headless: the kohya_ss README says that on a remote machine, native OS dialogs (the overwrite confirmation and local file pickers) run on the server process, and over SSH they can block training indefinitely. With --headless, the file and folder picker buttons are hidden, so you type paths, and the “overwrite existing model?” prompt is skipped: if the output name already exists, it is overwritten. Give each run its own output name.

Why 127.0.0.1: the GUI is then reachable only through your SSH login. The README examples use --listen 0.0.0.0; if you do that, also set --username and --password, which the CLI options list supports.

Step 5: Open the GUI through an SSH tunnel

On your own computer, not on the instance:

ssh -N -L 7860:127.0.0.1:7860 -p <ssh-port> <ssh-user>@<ssh-host>

Leave it running and open http://localhost:7860 in your browser. For more ports (for example TensorBoard on 6006) and troubleshooting, see How to use SSH port forwarding on a cloud GPU.

The docs examples also show --share. According to the Gradio sharing guide, a share link is served through Gradio’s share servers, is publicly accessible, and expires after 1 week. You do not need it when you use the tunnel.

Step 6: Put your base model and dataset on the instance, then train

Because --headless hides the file pickers, keep everything under one folder and type the paths:

mkdir -p ~/kohya-data/models ~/kohya-data/datasets ~/kohya-data/outputs
  • Base model: download it into ~/kohya-data/models; see How to download a Hugging Face model on a cloud GPU.
  • Dataset: upload your images and caption files into ~/kohya-data/datasets with scp, rsync or the JupyterLab upload button.
  • Defaults: the README describes a config.toml in the kohya_ss folder (copy config example.toml) that pre-fills paths such as model_dir, output_dir and logging_dir. For folders outside the kohya_ss directory, it documents a [server] section with allowed_paths.
[server]
allowed_paths = ["/root/kohya-data"]

Use the absolute path of your own folder (echo ~/kohya-data prints it). In the GUI, open the LoRA tab, enter the model, dataset and output paths, set an output name, and start training. To watch GPU use while it trains, run nvidia-smi in a second SSH session; see How to check GPU utilization on a cloud GPU.

Alternative: the pip method

If you prefer a classic virtual environment, the kohya_ss pip docs use setup.sh and gui.sh. setup.sh looks for python3.11, then python3.10, so check python3.11 --version first; the docs also show a conda route with conda create -n kohyass python=3.11.

cd ~/kohya_ss
chmod +x setup.sh gui.sh
./setup.sh
./gui.sh --headless --listen 127.0.0.1 --server_port 7860

gui.sh stops with “Please run setup.sh first or activate a conda environment” if it finds neither the venv folder nor an active conda environment.

Check your own setup

These are checks you can run yourself; this page does not assume the result.

  • Driver and CUDA: the nvidia-smi header shows a CUDA Version of 12.8 or higher.
  • tkinter: the README’s troubleshooting section covers “No module called tkinter”. In the kohya_ss folder, uv run python -c "import tkinter" should print nothing. If it fails, the README suggests reinstalling Python, and the kohya_ss uv Linux prerequisites install python3.11-tk with apt.
  • GUI is listening: on the instance, curl -sI http://127.0.0.1:7860 should return an HTTP status line.
  • PyTorch sees the GPU: cd ~/kohya_ss && uv run python -c "import torch; print(torch.__version__, torch.cuda.is_available())" should print a +cu128 version and True.

Before you destroy the instance

According to /terms, data on the instance is permanently deleted when you destroy it. Copy your trained .safetensors files, sample images, logs and config.toml to your computer first, for example:

rsync -avP -e "ssh -p <ssh-port>" <ssh-user>@<ssh-host>:kohya-data/outputs/ ./kohya-outputs/

GPU time is billed per minute, rounded up, with a 1-minute minimum, and billing stops when you destroy the instance; see /terms.

FAQ

How do I run Kohya_ss on a remote GPU server?

Clone bmaltais/kohya_ss with git clone --recursive, install uv, and start the GUI with ./gui-uv.sh --headless --listen 127.0.0.1 --server_port 7860. Then open an SSH tunnel from your computer with ssh -N -L 7860:127.0.0.1:7860 and browse to http://localhost:7860.

Why does Kohya_ss hang or show no file picker over SSH?

The kohya_ss README says that without --headless, native dialogs such as the overwrite confirmation and file pickers run on the server and can block training indefinitely over SSH. With --headless, the picker buttons are hidden, so you type paths, and an existing output name is overwritten without a prompt.

Which Python version does Kohya_ss need?

On 2026-10-29, the repository’s .python-version file read 3.11 and pyproject.toml required Python 3.10 or later and below 3.12. The uv method uses .python-version, and uv downloads that Python automatically if the system does not have it.

Should I use --share to open the Kohya GUI from my browser?

You do not need it if you use an SSH tunnel. According to the Gradio sharing guide, a share link goes through Gradio’s share servers, is publicly accessible, and expires after 1 week. If you listen on 0.0.0.0 instead of 127.0.0.1, set --username and --password.

How is the GPU billed while Kohya_ss trains?

GPU time is billed per minute, rounded up, with a 1-minute minimum, and billing stops when you destroy the instance. Copy your LoRA files off first, because data on the instance is deleted on destroy. See https://cloudgpu.app/terms for the full billing terms.

Sources