A LoRA is a small add-on file that teaches an image model something new: an art style, a product, a mascot, or a character you designed. Training one used to mean wrestling with scripts and config files.
Today, Ostris AI Toolkit gives you a web interface where you upload images, pick a model and press start, and it runs on your own NVIDIA GPU.
This guide walks you through the whole process: installing AI Toolkit, preparing a good dataset, writing captions, choosing settings, training a LoRA for Flux, Qwen-Image, Z-Image, SDXL and others, testing it in ComfyUI, and fixing the problems that trip up most first-timers.
Install steps and defaults come from the official AI Toolkit README and example configs as of November 2026.
- Tool: Ostris AI Toolkit.
git clone https://github.com/ostris/ai-toolkit.git, then runrun_windows.bat(orrun_linux.sh). The UI opens athttp://localhost:8675. - Dataset: 15 to 40 good images (jpg, jpeg or png), each with a matching
.txtcaption. No need to crop or resize. - Starting settings (Flux example): rank 16, learning rate 1e-4, 2,000 steps, batch size 1, adamw8bit, save and sample every 250 steps.
- Use a trigger word and put
[trigger]in captions or sample prompts. - VRAM: the Flux example config is built for 24 GB. Smaller models such as SDXL, SD 1.5 or Z-Image need less.
- Test: copy the
.safetensorstoComfyUI/models/loras/and load it with a LoRA loader.
What a LoRA Is and What to Train
LoRA stands for Low-Rank Adaptation. Instead of retraining a whole multi-gigabyte model, you train a small set of extra weights (often tens to a few hundred megabytes) that sit on top of it. Load the LoRA and the model gains the new concept; remove it and the model goes back to normal.
| LoRA type | Good dataset | Example use |
|---|---|---|
| Style | 20 to 40 images in one consistent art style | Your own illustration style, a watercolour look |
| Product or object | 15 to 30 photos from many angles | A shoe, a bottle, a logo mascot for ads |
| Original character | 15 to 30 images of a character you created | A game or comic character in new poses |
| Concept | 20+ images showing one idea | A lighting style, a type of scene |
Use images you own or have permission to use. Do not train LoRAs of real people without their clear consent, and never to make misleading or explicit images of anyone.
What You Need
- An NVIDIA GPU. The README lists an NVIDIA GPU “with enough ram to do what you need”. The Flux example configs are named for 24 GB cards. Smaller models train on less. Mac support in the manager is experimental.
- Git to download the toolkit.
- Disk space: base models download from Hugging Face and can be tens of gigabytes.
- A Hugging Face account and token for gated models such as FLUX.1-dev (accept the licence on the model page first).
No suitable GPU? You can rent one by the hour. Our Vast.ai guide shows how to get a cheap cloud GPU.
Install AI Toolkit
Option A: AI Toolkit Manager (recommended, experimental)
The manager detects your hardware, installs the right PyTorch build, creates a Python environment and fetches local copies of Node.js and FFmpeg, all inside the ai-toolkit folder.
- Install git.
- Open a terminal and run
git clone https://github.com/ostris/ai-toolkit.git, thencd ai-toolkit. - Windows: double-click
run_windows.bat. Linux:chmod +x run_linux.shthen./run_linux.sh. Mac (experimental):./run_mac.zsh. - Wait for the first-time setup to finish. The UI starts at
http://localhost:8675.
The manager checks for updates each time it starts. Handy terminal commands: python3 -m manager install, update, launch and doctor (to diagnose problems).
Option B: Manual install
Requirements from the README: Python 3.10 or newer (3.12 recommended), a venv, git and Node.js newer than 20 for the UI.
git clone https://github.com/ostris/ai-toolkit.git
cd ai-toolkit
python -m venv venv
.\venv\Scripts\activate (Linux: source venv/bin/activate)
pip install --no-cache-dir torch==2.13.0 torchvision==0.28.0 torchaudio==2.11.0 --index-url https://download.pytorch.org/whl/cu130
pip install -r requirements.txt
cd ui
npm run build_and_start
If Windows gives you trouble, the README recommends the community AI-Toolkit-Easy-Install script by Tavris1.
Running on a server? Protect the UI with a password by setting AI_TOOLKIT_AUTH before starting it, for example set AI_TOOLKIT_AUTH=your_password && npm run build_and_start on Windows.
Prepare Your Dataset
Your dataset matters more than any setting. A small set of excellent images beats a big pile of average ones.
- Collect 15 to 40 images. Sharp, well lit, no watermarks or text overlays.
- Add variety. Different angles, backgrounds, lighting and framing. If every photo has the same background, the LoRA learns the background too.
- Use jpg, jpeg or png. The README notes WebP currently has issues, so convert WebP files first.
- Do not crop or resize. AI Toolkit never upscales, but it downscales and sorts images into aspect-ratio buckets automatically.
- Put them in one folder, for example
datasets/my_style/.
| Do | Avoid |
|---|---|
| High resolution (1024 px or more on the short side) | Tiny, blurry or heavily compressed images |
| Consistent subject or style | Mixing several unrelated styles |
| Varied backgrounds and poses | Near-duplicate images |
| Clean images | Watermarks, logos, captions burned into the image |
Write Good Captions
Each image needs a text file with the same name, such as image2.jpg and image2.txt, containing only the caption.
- Pick a trigger word that is not a real word, like
zxstyleorm4sc0t. - Use
[trigger]in captions. If you set a trigger word, AI Toolkit replaces[trigger]with it. If a caption has no trigger, it adds the trigger automatically. - Describe what changes, not what you want learned. For a style LoRA: “[trigger], a fox sitting on a rock at sunset”. For a product: “[trigger] bottle on a marble kitchen counter, morning light”.
- Keep captions natural. Modern models like Flux and Qwen-Image respond well to plain sentences.
- Use a vision model to draft captions if you have many images, then fix them by hand.
The UI also lets you edit captions next to each image when you create a dataset, which is the easiest way to work.
Train a LoRA in the UI
- Open
http://localhost:8675. - Add your Hugging Face token in Settings if you train on a gated model.
- Create a dataset: go to Datasets, create a new one, upload your images and check the captions.
- Create a job: go to New Job, give it a name, and choose the base model (for example FLUX.1-dev, Qwen-Image or Z-Image).
- Set the trigger word and select your dataset.
- Check the settings (see the next section). The defaults are a sensible start.
- Add sample prompts that use
[trigger]so you can watch the LoRA learn. - Start the job and monitor progress, loss and sample images in the UI.
The UI does not have to stay open for training to continue. It is only needed to start, stop and monitor jobs.
Settings Explained
Values below are from the official train_lora_flux_24gb.yaml example. They are a solid starting point for other models too.
| Setting | Example default | What it does | Tip |
|---|---|---|---|
| Rank (linear) / alpha | 16 / 16 | LoRA size and capacity | 8 to 16 for styles and objects, 32 for complex subjects |
| Steps | 2,000 | Total training steps | The config notes 500 to 4,000 is a good range |
| Learning rate | 1e-4 | How fast it learns | Lower (5e-5) if samples get burnt or over-saturated |
| Batch size | 1 | Images per step | Keep at 1 on consumer GPUs |
| Optimizer | adamw8bit | Training algorithm | Leave as is |
| Resolution | 512, 768, 1024 | Buckets the images are trained at | Drop 1024 to save VRAM |
| Caption dropout | 0.05 | Drops the caption 5% of the time | Helps the LoRA work with short prompts |
| Gradient checkpointing | on | Trades speed for lower VRAM | Keep on unless you have lots of VRAM |
| Quantize | on | Runs the base model in 8-bit mixed precision | Needed to fit Flux in 24 GB |
| Low VRAM | off | Uses less VRAM while quantizing, but slower | Turn on if the GPU also drives your monitors |
| Save every / Sample every | 250 / 250 | How often checkpoints and test images are made | Lets you pick the best checkpoint, not just the last |
| EMA | on (0.99) | Smooths learning | The config recommends leaving it on |
Pick the best checkpoint, not the last. Look through the sample images. The best LoRA is usually the step where the subject or style is clear but the images still look natural. After that point it often starts to overfit.
Which Base Model to Train On
AI Toolkit supports a long list of models. Train on the model you plan to generate with, because a LoRA only works with the model family it was trained for.
| Base model | Good for | Notes |
|---|---|---|
| FLUX.1-dev | Photoreal products and styles | Gated licence; example configs target 24 GB |
| Qwen-Image / Qwen-Image 2.1 | Text in images, design styles | 2.1 can also train edit LoRAs when your dataset has control images |
| Z-Image / Z-Image Turbo | Fast generation styles | Lighter than Flux |
| SDXL | Huge ecosystem, lower VRAM | Great first LoRA on 12 to 16 GB |
| SD 1.5 | Old GPUs | Lowest requirements |
| Wan 2.1 / 2.2, LTX-2 | Video LoRAs | Needs much more VRAM and time |
If you generate with Qwen-Image, see our Qwen-Image local guide. For Flux, see how to use Flux.
Test Your LoRA in ComfyUI
- Find the file in the training output folder (named after your job), for example
output/my_first_flux_lora_v1/my_first_flux_lora_v1.safetensors. Checkpoints from earlier steps are saved there too. - Copy it to
ComfyUI/models/loras/. - Add a LoRA loader (
LoraLoaderModelOnlyfor Flux and most modern models,Load LoRAfor SDXL and SD 1.5) between the model loader and the sampler. - Use your trigger word in the prompt.
- Try strengths from 0.6 to 1.0. Lower strength blends the LoRA more gently.
LoRA has no visible effect? Our ComfyUI LoRA not working fix covers every cause, from wrong base model to “lora key not loaded” errors. New to ComfyUI? Start with our ComfyUI beginner’s guide.
Training From a Config File
Prefer the command line? Copy an example config and run it directly:
- Copy
config/examples/train_lora_flux_24gb.yamlinto theconfigfolder and rename it, for examplemy_style.yml. - Edit the name,
folder_pathof your dataset, trigger word and sample prompts. On Windows, escape backslashes:"C:\\path\\to\\images". - Run
python run.py config/my_style.yml.
You can stop training with Ctrl+C and it resumes from the last checkpoint next time. The README warns not to press Ctrl+C while a checkpoint is saving, or that checkpoint will likely be corrupted.
Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
| CUDA out of memory | Model too big for your GPU | Turn on quantize and low VRAM, drop the 1024 resolution, or train a smaller model. See our CUDA out of memory fix |
| 401 or access error downloading the model | Gated model, licence not accepted or no token | Accept the licence on Hugging Face and add your token |
| Images are skipped | WebP or other unsupported format | Convert to jpg or png |
| Captions ignored | Caption file name does not match the image | Use the same name with a .txt extension |
| Samples look burnt or over-sharpened | Overtraining or learning rate too high | Use an earlier checkpoint or lower the learning rate |
| LoRA barely changes anything | Too few steps or weak dataset | Train longer, improve dataset variety, use the trigger word |
| Every image has the same background | Dataset backgrounds too similar | Add varied backgrounds and describe them in captions |
| UI will not start | Node.js missing or too old | Install Node.js newer than 20, or use the manager |
| Something else is broken | Environment problem | Run python3 -m manager doctor |
FAQ
How many images do I need to train a LoRA?
15 to 40 good, varied images is a practical range for most styles, objects and characters. Quality matters more than quantity.
How long does training take?
It depends on the model, steps and GPU. A 2,000-step Flux LoRA on a 24 GB card usually takes a few hours; SDXL and smaller models are faster.
Can I train a LoRA on 8 or 12 GB VRAM?
Smaller models such as SD 1.5 and SDXL are the realistic choice. Large models like Flux are designed around 24 GB in the example configs.
Can I train without a GPU?
Not practically on a CPU. Rent a cloud GPU instead; the README also mentions RunPod, Modal and Ostris Cloud options.
Does a Flux LoRA work with SDXL?
No. A LoRA only works with the model family it was trained on.
Can I sell images made with my LoRA?
That depends on the base model’s licence. FLUX.1-dev, for example, has a non-commercial licence. Check the licence of the model you trained on.
Is AI Toolkit free?
Yes. It is open source and runs on your own hardware.




