AutoDescribe-Images

Tool to automatically generate text descriptions (captions) for images using Ollama vision models (LLaVA, Qwen3-VL, Llama Vision). Available as a web application (recommended) or CLI.

Key feature: Fully customizable system prompts to precisely control the output format. Includes built-in presets optimized for Stable Diffusion (with parentheses weight syntax), Z-Image/Midjourney (detailed structured descriptions), Flux, and more.

Use Case

Perfect for AI image generation training! This tool is designed to help you create caption files for training LoRA (Low-Rank Adaptation) models on image generation AI like Stable Diffusion, Flux, Z-Image, or other diffusion models.

When training a LoRA, each image in your dataset needs an accompanying .txt file with a description. This tool automates that process by:

Analysis of each image using a visual AI model, with your personalized instructions in natural language
Generating detailed, consistent descriptions tailored to your target model

Prerequisites

Git - Version control
uv - Python package manager (handles Python installation automatically)
Ollama - Must be installed separately and running

Installing Git

Check if Git is already installed:

git --version

If not installed, download it from git-scm.com and follow the installation instructions for your OS.

Installing uv

uv is a fast Python package manager. First, check if you already have it installed:

uv --version

If not installed, run one of these commands:

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

After installation, restart your terminal to ensure uv is available in your PATH.

Installing Ollama

Download and install Ollama from ollama.com, then pull a vision model:

ollama pull qwen3-vl:4b

Installation

# Clone the repository
git clone https://github.com/hydropix/ollama-image-describer.git
cd ollama-image-describer

# Install Python dependencies with uv
uv sync

Note: uv sync installs the Python dependencies (including the ollama Python client library). The Ollama server itself must be installed separately as described above.

Configuration

Environment Variables (.env)

Create a .env file from the example:

cp config/.env.example .env

Configure your Ollama server:

OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=qwen3-vl:4b

Prompt Configuration (config/config.yaml)

The config/config.yaml file contains prompt presets and default settings. The system prompt is fully customizable, allowing you to precisely control the output format to match your specific needs.

Built-in Presets

The tool includes presets optimized for different image generation models:

Preset	Target Model	Description
Z-Image	Z-Image	Very detailed, structured descriptions with markdown formatting. Focuses on composition, lighting, textures, and atmosphere with poetic precision.
Stable Diffusion	SD, SDXL, Forge	Tag-based prompts with weight syntax `(element:1.2)`. Uses parentheses for emphasis and quality boosters like `(masterpiece:1.2), (best quality)`.
Simple	General use	Concise, straightforward descriptions without special formatting.

Example: Stable Diffusion Preset Output

(masterpiece:1.2), (best quality), 1girl, long flowing red hair, (emerald green eyes:1.3),
elegant black dress, standing in flower field, soft golden hour lighting, (bokeh:1.1),
depth of field, vibrant colors, digital painting style, highly detailed

Example: Z-Image Preset Output

## Subject
**Young woman** with flowing auburn hair, wearing a vintage emerald dress

## Composition & Setting
Wide shot capturing a sunlit meadow with wildflowers in the foreground

## Lighting & Atmosphere
*Golden hour lighting* casting warm shadows, *soft diffused glow* from the setting sun

Creating Custom Presets

Add your own presets in config/config.yaml to tailor outputs for your specific workflow:

prompts:
  # Your custom preset
  flux:
    name: "Flux"
    markdownFormat: false
    prompt: |
      Generate a natural language description optimized for Flux models.
      Focus on clear, descriptive sentences without weight syntax.
      Describe the scene as if telling a story...

  my_custom:
    name: "My Custom Style"
    markdownFormat: false
    prompt: |
      Your custom instructions here...
      Be specific about the output format you want.

defaults:
  temperature: 0.7
  model: "qwen3-vl:4b"

The markdownFormat option controls whether the output uses markdown styling (headers, bold, italics) or plain text.

Usage

Important: All commands must be run from the project directory (ollama-image-describer).

Web Interface (Recommended)

Launch the web interface for an easier experience:

cd ollama-image-describer
uv run python -m image_describer --web

CLI Mode

uv run python -m image_describer <image_folder> [options]

Options

Option	Short	Description
`--web`	`-w`	Launch the web interface
`--config`	`-c`	Path to YAML config file
`--prefix`	`-p`	Text prepended to each description
`--suffix`	`-s`	Text appended to each description (e.g., ", By Artist")
`--overwrite/--no-overwrite`		Overwrite existing .txt files (default: overwrite)
`--verbose`	`-v`	Verbose mode

Examples

# Launch web interface
uv run python -m image_describer --web

# Basic CLI usage
uv run python -m image_describer ./my_images

# With prefix and suffix
uv run python -m image_describer ./my_images --prefix "A photo of " --suffix ", By Kristof"

# Verbose mode with custom config
uv run python -m image_describer ./my_images -v -c custom_config.yaml

Supported Models

⚠️ Important: This tool requires a vision model capable of analyzing images. Standard text-only models (like llama3, mistral, etc.) will not work.

Browse all available vision models: Ollama Vision Models

Recommended vision models:

Qwen3-VL (recommended): qwen3-vl:4b
LLaVA: llava, llava:13b
Llama Vision: llama3.2-vision

License

MIT

Specs

README