Getting started

LoRA Dataset Studio turns one reference photo into a trained, ranked LoRA — curation, captioning, face-scoring and training behind a single browser tab, on your own machine. The useful part of LoRA training isn't the training; it's building a clean, balanced, well-captioned image set. This app puts that whole pipeline behind one UI.

In a hurry? Launch the app, let the Setup wizard scan your machine, and create your first dataset from your own photos — no API key, no GPU, no external tool required for that first step.

You can start API-only and add the local tools later — features light up automatically when their tool is detected.

Windows (one command): download LoRA-Dataset-Studio-windows.zip from the latest release, extract it, then double-click start.bat. Releases contain an archive/source, not a prebuilt executable launcher. start.bat finds or downloads a compatible Python (3.10–3.12), creates .venv, installs the requirements, and opens the app at http://127.0.0.1:5050/.

Any OS (manual venv):

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r backend/requirements.txt
python backend/run.py

Pinokio (one click, any OS): in Pinokio, use Discover → Download from URL with https://github.com/perfectgf/lora-dataset-studio.git, then Install and Start. Pinokio creates the environment (env/), installs the core requirements and opens Studio on the port it really bound. Two things to know: the optional tools are still connected from Setup, and updates go through Pinokio's Update tab — it runs the same git pull --ff-only as the in-app updater. You do not have to remember that last part: the app recognises a Pinokio launch and its Updates card shows Stop → Update → Start (with how many commits behind you are) instead of the Update & restart button, which would relaunch the server in a window Pinokio no longer tracks.

Docker (API-only): cp .env.example .env, then docker compose up --build.

Docker (GPU, with ComfyUI inside): cp .env.example .env, then mkdir -p run basedir data-docker-gpu bank-images — create those yourself, or Docker creates them as root and the app cannot write to them — then docker compose -f docker-compose.gpu.yml up --build. Needs an NVIDIA GPU and the NVIDIA Container Toolkit; this is the only Docker option that can do Klein/Z-Image generation and the Test Studio.

The CUDA 12.x compatibility minimum is driver 525.60.13 on Linux or 528.33 on Windows/WSL; for the default CUDA 12.9 image, use at least 575.51.03 on Linux or 576.02 on Windows. The optional CUDA 13 image needs R580+. If you reuse an existing ComfyUI tree, LDS_COMFY_BASEDIR must name the parent that directly contains models/, input/, output/ and custom_nodes/, not the models/ folder itself. Compose actively defaults DNS to 1.1.1.1; set LDS_DNS to your router or Pi-hole when internal hostnames matter.

Both ports are published on the host and remain reachable from the LAN. A Settings restart is handled by the container supervisor and keeps the fixed container bind. To update this Docker flavour, update and rebuild the image rather than trying to replace /app in place:

git pull
docker compose -f docker-compose.gpu.yml up -d --build

If /data or existing contents beneath it are not writable, LDS_FORCE_CHOWN=true is the last resort: it recursively changes ownership only for the LDS_DATA mount, never the ComfyUI or bank mounts.

See Installation for all launchers, updates and external tools, and Requirements for hardware and dependencies.

A full-local install is three separate programs, in two folders, on two ports, with two Python environments. Nothing in the app used to say so, and the cost of guessing is real: a user spent hours patching ai-toolkit's own web UI — a component this app never talks to — while the actual problem was one line of config.json (reported by strouder, GitHub #19).

Two consequences worth remembering:

• The Studio reads config.json and drives training. That file belongs to this app (it sits in its data folder, and every key in it has a field in Settings). Editing anything inside ai-toolkit's ui/ folder changes nothing here — if you ever find yourself editing ui/dist/…, you are in the wrong project.
• The two Python environments are not interchangeable. The Studio's .venv runs the web app; ai-toolkit's venv is the one that must have torch and the training dependencies. Settings ▸ Local tools ▸ Python interpreter is how you tell the app which interpreter is ai-toolkit's — and its Test button now checks that the interpreter can really import torch, not just that the file exists.

There is no process stacking to worry about on our side: the Studio is a single Flask process, and starting a second one on the same port fails loudly instead of running invisibly alongside the first.

• LoRA Dataset Studio: Python 3.10 – 3.12. start.bat finds or downloads one for you; the optional ML extras (insightface, onnxruntime, numpy<2) only publish wheels for those versions.
• ai-toolkit: Python 3.11 is the safe choice. On 3.13 its pinned scipy==1.12.0 has no wheel, pip falls back to building from source and dies on a missing Fortran compiler (measured and reported by strouder, GitHub #19). On Windows, install 3.11.9 — it is the last 3.11 with a binary installer; later 3.11.x are source-only security releases.
• Or hand that whole job to ai-toolkit. Run python -m manager install from the ai-toolkit folder and its own installer provisions a Python it supports, reads your NVIDIA driver, installs the CUDA build of PyTorch that matches it and creates the venv next to run.py — all inside that folder, nothing system-wide. The Studio then detects that interpreter on its own. This is the step worth not improvising: a plain pip install torch on Windows installs a CPU-only wheel, ai-toolkit trains on the CPU without a word, and the run looks alive for hundreds of hours (see The card never fills at all: the run is on the CPU). Use the install subcommand rather than run_windows.bat, which finishes by starting ai-toolkit's own web UI — the one this app never talks to.
• The two do not have to match. They are separate environments on purpose.

If a base-model download dies with something that reads like a network error, check whether HF_HUB_ENABLE_HF_TRANSFER=1 is set in your environment. That turns on an optional fast-download accelerator which needs the hf_xet (or hf_transfer) package installed in the environment doing the downloading; without it, transfers abort with a misleading message. This app never sets that variable — it comes from your shell, ai-toolkit's .env, or a ComfyUI launcher. Either fix works: set HF_HUB_ENABLE_HF_TRANSFER=0, or pip install hf_xet. The training failure panel now recognises this case and says so. (Reported by bobba84, GitHub #18.)

On first launch, Open LDS opens the dataset workspace. You can create a dataset, import your images, edit captions and export it without installing a plugin or downloading a model. Completing this step saves the setup state so later visits return to the application.

Choose an optional goal when you need more: captioning prepares the shared vision tools; local generation prepares ComfyUI and its selected models; Plugins opens one list for browsing and managing plugins, with All, Installed and Updates filters. Nothing is downloaded by choosing a goal or visiting a plugin page.

To install several plugins, tick them in Plugins, choose Review selected, and confirm the shared plan. All selected packages are checked before any changes are staged; one LDS restart applies the whole selection.

To update installed plugins, choose Update all and review the available updates together. Update all and restart downloads and verifies the complete selection, prepares one transaction and restarts LDS once. The page reloads when the new server is ready. Disabled plugins stay disabled; connected private catalogs keep their own signature checks. If your launcher requires a manual restart, LDS shows its restart instructions after preparing the updates. Active local work can postpone the restart; the prepared updates remain available to apply when it finishes. A retained cloud pod does not block a restart that keeps its plugin enabled.

Each plugin's card offers Install, or its controls once installed: open the plugin, Settings, turn it on or off, and update it when available. More actions contains Remove plugin. Installed plugins remain listed even if they are absent from the catalog or the store is offline. Purchases remains a separate tab for your licenses.

For preparation, open Settings on the plugin's card. Select the components you want, then prepare that selection. The server checks the whole plan before starting and displays progress and any failures. A completed download means the component is prepared; Re-check verifies availability. New custom nodes may need a ComfyUI restart before they appear.

Shared tools remain available from Setup. Their installers use managed environments and show the prerequisites for each component. Optional tools do not prevent you from opening the dataset workspace.

If something that worked stops working, the setup notice names it and links to the relevant check. A tool that was never installed is not a regression, and a stopped ComfyUI or Ollama can be started only when you need it.

• Datasets — the home tab and your library: photo tiles of every dataset, grouped by model family, with a search box and a badge for each family you've already trained. Create one and work it through the guided flow (source → curate → caption → train).
• 🏋️ Runs — every training in one place, cloud and local: live progress, the settings each launch used, retry a failed run (↻), continue a finished one (▶), and download the LoRA (appears once ai-toolkit or a vast.ai key is set).
• Test Studio — grid-test a trained LoRA across checkpoints and strengths, vote, and rank (appears once ComfyUI is reachable).
• Guide — this manual.
• Setup — the guided wizard, re-runnable anytime.
• Settings — everything the wizard configures, plus server, updates, maintenance and the diagnostic report.

Next chapter: Using the app — the full walkthrough, dataset type by dataset type.