---
license: apache-2.0
pipeline_tag: image-text-to-text
tags:
- captioning
- joycaption
- joytag
- dataset-preparation
- gradio
base_model:
- fancyfeast/llama-joycaption-beta-one-hf-llava
- fancyfeast/joytag
---

# JoyCaption Batch WebUI

A single-window local Gradio UI for **[JoyCaption Beta One](https://huggingface.co/fancyfeast/llama-joycaption-beta-one-hf-llava)** (8B captioning VLM) and **[JoyTag](https://huggingface.co/fancyfeast/joytag)** (fast ViT Danbooru tagger), built for **LoRA / fine-tune dataset prep**:

- **Batch folder captioning** — point it at a dataset folder and it writes a `.txt` next to each image (kohya / diffusion-pipe style), with *skip-existing* and an optional *trigger-word prefix*.
- **All JoyCaption caption types** — Descriptive, Straightforward, Stable Diffusion prompt, Danbooru/e621/Rule34/booru tags, Art Critic, Product Listing, and more, plus length control and the full extra-options list, with a live editable prompt.
- **JoyTag tab** — near-instant Danbooru tagging (~0.4 GB VRAM), single image with confidence scores or whole folders, threshold slider, underscores→spaces toggle. Loads/unloads independently of the big model.
- **VRAM control** — Load/Unload buttons free VRAM without closing the app (handy for switching back to ComfyUI), and a 4-bit NF4 mode (~7 GB) lets it run alongside a diffusion UI on one GPU.
- **Streaming output**, copy-to-clipboard, LAN mode (`--listen`).

> 🖥️ **This is a local tool, not a hosted demo** — batch mode reads dataset folders on your own disk, so clone it and run it on your own GPU. Main repo: **https://github.com/justineightyone/joycaption-batch-webui** (this HF repo is a mirror).

## Requirements

- NVIDIA GPU: **~18 GB VRAM** in bf16 (RTX 3090/4090 class) or **~7 GB** with `--nf4` (RTX 3060 12GB and up work fine)
- Python 3.10+
- ~17 GB disk for the JoyCaption model (auto-downloaded on first caption into `./models`)

## Install & run (Windows)

```
git clone https://github.com/justineightyone/joycaption-batch-webui
cd joycaption-batch-webui
install_windows.bat
start_windows.bat          (full quality, ~18 GB VRAM)
start_windows_lowvram.bat  (4-bit NF4, ~7 GB VRAM)
```

## Install & run (Linux)

```
git clone https://github.com/justineightyone/joycaption-batch-webui
cd joycaption-batch-webui
bash install_linux.sh
./start_linux.sh           # add --nf4 for the ~7 GB mode
```

The UI opens at http://127.0.0.1:7861 (port chosen to never collide with ComfyUI's 8188 or A1111's 7860).

Flags: `--nf4` (4-bit), `--port N`, `--listen` (LAN access), `--cache-dir PATH` (where models download; default `./models`).

## Usage notes

- The model loads on the **first caption** (or the Load button). The **Unload** button frees VRAM without closing the app.
- **Batch Folder** writes `image_name.txt` next to each image. *Skip existing* is on by default, so you can re-run a folder after adding images.
- The **prompt box is editable** — the dropdowns build the prompt, but you can hand-tweak it before captioning.
- JoyTag is a different model (a 91M-param ViT classifier, not the VLM) — use it when you want fast, consistent booru tags rather than prose.

## Performance

Defaults are tuned for Ampere+ GPUs: bf16 weights, SDPA attention, TF32 matmul, whole model on GPU. On an RTX 3090 that's roughly **6–10 s per caption** in bf16. JoyTag is near-instant per image.

## ⚠️ Gradio version

Pinned to **gradio==6.12.0**. Gradio 6.14.0 has a rendering regression that hides the Caption Type / Caption Length dropdowns and stops the prompt from updating. If the dropdowns ever look broken, you've been auto-upgraded — fix with:

```
pip install gradio==6.12.0
```

## Credits & license

- **JoyCaption** and **JoyTag** models and original code by [fancyfeast (fpgaminer)](https://github.com/fpgaminer/joycaption) — Apache-2.0. JoyCaption is free, open, and uncensored; if you find it useful, go star the upstream project.
- UI derived from the HF Spaces [fancyfeast/joy-caption-beta-one](https://huggingface.co/spaces/fancyfeast/joy-caption-beta-one) and [MegaTronX/JoyCaptionBetaOne](https://huggingface.co/spaces/MegaTronX/JoyCaptionBetaOne).
- `joytag_models.py` is from the official [fancyfeast/joytag](https://huggingface.co/spaces/fancyfeast/joytag) Space.

This repo is licensed **Apache-2.0** (see [LICENSE](LICENSE)).