Skip to content

photo-tagger

photo-tagger sends each photo to a local vision-language model and writes Lightroom-compatible metadata: a title, a short description, and hierarchical keywords. It comes as a command-line tool and an optional desktop app, which share one pipeline and one config file. By default it leaves your originals untouched, writing an XMP sidecar next to each image instead of modifying the file.

Highlights

  • Works with RAW and standard formats (CR3, CR2, NEF, DNG, JPG, PNG, and more). RAW files are decoded with rawpy/libraw and the rest with Pillow.
  • Generates a title, a short description, and hierarchical keywords in Lightroom's root-to-leaf pipe form, in any language you ask for with --output-language.
  • Merges new keywords with existing ones by default, or replaces them with --overwrite-keywords.
  • Snaps generated keywords onto your own Lightroom keyword list with --vocabulary, and harmonizes each shoot with --session-gap so every frame of one subject gets the same term.
  • Talks to local Ollama, LM Studio, or llama.cpp servers, or any hosted OpenAI-compatible API.
  • A doctor command that pre-flights ExifTool and the model provider before a run.
  • A watch command that tags photos as they land in an import folder.
  • An undo command that puts back what a run wrote, down to the last sidecar.
  • Optional PySide6 desktop GUI (photo-tagger gui) for a point-and-click workflow, carrying the same vocabulary, shoot-harmonization, watch, and undo features, translated into English and Brazilian Portuguese.
  • Sends a compact, resized JPEG to the model to save tokens, with configurable dimensions and quality.
  • Optional SQLite cache so reruns skip the model call when nothing relevant changed.
  • Processes photos concurrently with a thread pool when the model server can keep up.
  • Skip and resume support: skip already-tagged files, skip names from a list, and append successes to a skip file as the run progresses.
  • Optional NDJSON output on stdout, one line per photo, that pipes cleanly into jq, plus a JSON run summary and a per-photo CSV report.
  • Timestamped, rotating log files plus a live progress bar on a TTY.
  • Configurable through CLI flags, environment variables, and a TOML config file.

Quick start

The recommended way to install photo-tagger is with uv:

uv tool install photo-tagger

Once installed, tag a folder of CR3 and JPG files, recursing into subdirectories:

photo-tagger -i ./photos --ext cr3,jpg -r

Tip

photo-tagger needs ExifTool on your PATH and a running Ollama or LM Studio server exposing a vision-language model. See Installation for the full setup, including libraw for RAW decoding.

Where to go next

  • Getting started: install photo-tagger and learn how to configure it.
  • Usage: run the tool, with a full CLI reference and practical recipes.
  • Architecture: how the processing pipeline, AI providers, metadata, and caching fit together.
  • Development: set up the project, run tests, and keep code quality high.
  • License: photo-tagger is released under the MIT License.