# OneTrainer: a GUI and CLI for Diffusion fine-tuning, LoRA and embeddings

> OneTrainer wraps diffusion training for FLUX, SDXL, Stable Diffusion and video models behind a desktop UI and a set of Python scripts. It is a good fit when you want one tool for LoRA, full fine-tuning and dataset captioning, and a poor fit when you need a stable, versioned release to pin.

**Nerogar/OneTrainer** — OneTrainer is a one-stop solution for all your Diffusion training needs.

- Repository: https://github.com/Nerogar/OneTrainer
- Stars: 3,224 · Forks: 333
- Language: Python
- License: AGPL-3.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/nerogar-onetrainer

## What OneTrainer actually replaces in a diffusion training workflow

Training a diffusion model is a chain of small jobs: caption the dataset, generate masks if you want masked training, pick a base model format, configure the training method, run it, sample intermediate checkpoints, and convert the result. OneTrainer's pitch is that all of those live in one application. The README lists the supported models as Ernie Image, Z-Image, Qwen Image, FLUX.1, Flux.2 Dev and Klein, Chroma, Stable Diffusion 1.5 through 3.5, SDXL, Würstchen-v2, Stable Cascade, PixArt-Alpha, PixArt-Sigma, Sana, Hunyuan Video and inpainting models, and the training methods as full fine-tuning, LoRA and embeddings. That breadth is the point. If you train LoRAs for several architectures, you are not switching tools per base model. The audience is therefore people who already run local training: hobbyists with a single consumer GPU, and small teams that want a shared procedure rather than a bespoke script per project. It is not aimed at someone who wants to rent a hosted endpoint and never touch Python.

## How the training pipeline is put together

The repository layout separates the UI from the work. The top level holds modules/, scripts/, training_configs/, training_presets/, models/ and resources/, with install and update scripts for Windows and Unix. The README describes the CLI as split into scripts in the scripts directory: train.py as the central training script, train_ui.py, caption_ui.py, convert_model_ui.py, convert_model.py, sample.py, create_train_files.py, generate_captions.py, generate_masks.py and calculate_loss.py. That split tells you something about the design: the GUI is a front end over the same operations the scripts expose, and the README states that all CLI commands need to be run inside the virtual environment created during installation. Several training features are wired into that pipeline rather than bolted on. Aspect ratio bucketing creates buckets automatically from your target resolutions, multi-resolution training runs several resolutions at once, and each image can carry multiple prompts. Noise scheduler rescaling follows the paper "Common Diffusion Noise Schedules and Sample Steps are Flawed". EMA training is supported, with the option to keep EMA weights in CPU memory to reduce VRAM use. Automatic backups run during training and, per the README, include all information needed to continue training, which is the closest thing here to a resume mechanism.

## Installing OneTrainer and running a first LoRA job

The README is explicit about the Python constraint: installing OneTrainer requires Python >=3.10 and <3.14. Clone the repository and run the platform installer.

```bash
git clone https://github.com/Nerogar/OneTrainer.git
cd OneTrainer
./install.sh
```

On Windows you would double click install.bat instead. The manual path, if the automatic script fails, is a virtual environment plus the requirements file.

```bash
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

The README notes that some Linux distributions are missing packages. On Ubuntu you must install libGL, and Alpine, Arch and Xubuntu may be missing tkinter, installed via apk add py3-tk on Alpine and sudo pacman -S tk on Arch. Once installed, launch the GUI.

```bash
./start-ui.sh
```

On Windows the equivalent is start-ui.bat. For a headless run, the README points at the scripts directory; every script takes -h, for example python scripts/train.py -h, and the README also references docs/QuickStartGuide.md and a create_train_files.py utility for building the files needed when training only from the CLI. Since this review has not run any of these commands, treat the script names and flags as documented rather than verified here: check -h output on your own checkout before scripting a run.

## Where OneTrainer gets in your way

The installation model is the first constraint. There are no retrieved releases, and the README's update path is update.bat or update.sh, or a manual git pull followed by pip install -r requirements.txt --force-reinstall. That means the canonical way to run OneTrainer is on the tip of master. If you need to reproduce a training run months later, your only anchor is a commit hash you recorded yourself. The README does not document rollback to a previous version. The second constraint is the dependency surface: requirements.txt pulls in requirements-cuda.txt and requirements-global.txt, with separate requirements-rocm.txt, requirements-cuda-legacy.txt and requirements-default.txt files alongside. Choosing the wrong one is a plausible first-run failure, and --force-reinstall on update can churn a large dependency tree. Third, the project's issue policy is strict: the README states that a debug_report.log is required for GitHub issues and that failure to provide it will lead to the issue being closed in most circumstances. Debug export is export_debug.bat on Windows or ./run-cmd.sh generate_debug_report elsewhere. If you cannot run those, your bug report has a short life. Finally, the README does not describe a rollback mechanism for a corrupted run beyond the automatic backups, so verify the backup directory contents before trusting a long job.

## OneTrainer against Kohya and AI-Toolkit

The comparison people search for is OneTrainer vs Kohya, and the architectural difference is the interface layer. Kohya's scripts are the reference implementation many trainers wrap; OneTrainer instead builds its own GUI and CLI around a modules/ package, and exposes dataset tooling in the same application: BLIP, BLIP2 and WD-1.4 captioning, plus ClipSeg or Rembg for masked training masks, plus a sampling UI so you do not switch applications to check progress. Against AI-Toolkit, which the search data pairs with OneTrainer, the difference is the same shape: OneTrainer ships a desktop UI and a set of local scripts, so the workflow stays on your machine and in your venv. That is a real trade-off. A local GUI application means you own the environment, the GPU drivers and the Python version, and you get the failure modes that come with them. A hosted or container-first trainer removes that class of problem at the cost of control over the exact training code. OneTrainer's answer to the environment problem is the install and update scripts plus the per-accelerator requirements files, which is a partial answer: it standardizes setup, not reproducibility.

## Maintenance, licensing and the cost of keeping it current

The repository is not archived, and the last push was on 2026-09-14, so the project is being changed. That also means the update path is not optional in practice: the README tells users to run update.bat or update.sh before confirming a bug is reproducible, which implies master moves fast enough that stale checkouts are a common source of confusion. Budget for periodic re-installs of the dependency tree, and expect to re-check your training presets after updates since training_presets/ and training_configs/ are shipped in the repository and can change with it. On licensing, the repository carries AGPL-3.0 and a LICENSE.txt at the top level. The practical implication worth flagging without giving legal advice: AGPL-3.0 is a strong copyleft licence with a network-use clause, so if you plan to expose a modified OneTrainer as part of a hosted service, the obligations differ from permissive licences, and that question belongs with your own counsel rather than with this article. Training outputs such as LoRA weights are a separate question the README does not address.

## Conclusion

Adopt OneTrainer if you already have a working CUDA or ROCm Python environment and want one application that covers LoRA, embedding and full fine-tuning plus captioning and mask generation, with a GUI for day-to-day runs and scripts for headless jobs. Skip it if you need tagged releases to pin, a documented rollback path, or a training stack you can reproduce byte-for-byte six months from now, because the README describes installation from a git clone and updates by pulling master. Before committing a long run, verify your Python version is inside the >=3.10 and <3.14 window, that the right requirements file matches your accelerator, and that you can produce a debug_report.log, since the project states GitHub issues without it will usually be closed.

## FAQ

### What is OneTrainer?

OneTrainer is a Python application for diffusion training that offers a graphical interface and a command-line interface. Its README describes it as a one-stop solution for Diffusion training needs, covering full fine-tuning, LoRA and embeddings across models including FLUX.1, SDXL and the Stable Diffusion family.

### How do I manually install OneTrainer?

Clone the repository, enter the directory, create a virtual environment with python -m venv venv, activate it, then run pip install -r requirements.txt. The README requires Python >=3.10 and <3.14, and notes that some Linux distributions need extra packages such as libGL on Ubuntu or tkinter on Alpine and Arch.

### What are the key differences between OneTrainer and AI-Toolkit?

The README does not mention AI-Toolkit, so a direct feature comparison is not documented here. What the repository does show is OneTrainer's approach: a local desktop GUI plus scripts in the scripts directory, with dataset captioning, mask generation and model conversion bundled into the same application.

### How do I train a LoRA with OneTrainer?

The README lists LoRA as one of the supported training methods and points to docs/QuickStartGuide.md for a technically focused quick start, with the wiki for broader tutorials. For headless runs, scripts/train.py is described as the central training script, and python scripts/train.py -h prints its parameters.

### How do I use OneTrainer?

The README describes two primary modes: a graphical interface started with start-ui.bat on Windows or start-ui.sh on Unix-based systems, and a command-line interface made up of scripts in the scripts directory. The README recommends docs/QuickStartGuide.md for a quick start and the wiki for a broader overview.

### How do I install OneTrainer?

Clone the repository and run install.bat on Windows or install.sh on Linux and Mac, which the README calls the automatic installation. A manual installation is also documented: create a venv, activate it, and run pip install -r requirements.txt, with Python >=3.10 and <3.14 required.

## Sources

- [Issues](https://github.com/Nerogar/OneTrainer/issues)
- [License: AGPL-3.0](https://github.com/Nerogar/OneTrainer/blob/master/LICENSE)
- [Nerogar/OneTrainer on GitHub](https://github.com/Nerogar/OneTrainer)
- [README](https://github.com/Nerogar/OneTrainer/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nerogar-onetrainer