Skip to content

Image Namer

Rename image files based on their visual contents using AI vision models.

Image Namer is a Python tool that analyzes images using multimodal vision models and generates meaningful, descriptive filenames. No more IMG_2347.jpg or screenshot-23.png—get names like golden-retriever-puppy--running-in-park.jpg or sales-chart--2024-quarterly-results.png.

Choose your workflow: - GUI: Visual interface with image preview and table editing - CLI: Command-line tool for scripting and automation

Screenshot

Key Features

  • Vision-based naming: Uses AI models (Ollama/OpenAI) to analyze image content and generate descriptive filenames
  • Dual interface: Choose graphical (Qt6) or command-line workflow
  • Local-first: Defaults to Ollama with gemma3:27b for privacy-conscious users
  • Intelligent caching: Avoids repeated API calls by caching results per image content hash
  • Idempotent: Won't rename files that already have suitable names
  • Batch processing: Process entire folders with recursive scanning
  • Markdown reference updates: Automatically updates links in your markdown/Obsidian notes
  • Manual editing: Double-click names in GUI to customize before applying
  • Dry-run mode (CLI): Preview changes before applying them
  • Smart collision handling: Automatically resolves filename conflicts

Quick Example

Graphical Interface: 

# Launch GUI
image-namer-ui

# Then: Open Folder → Process → Review → Apply

Command Line: 

# Preview what a file would be renamed to
image-namer file vacation-photo.jpg

# Apply the rename
image-namer file vacation-photo.jpg --apply

# Process entire folder (dry-run by default)
image-namer folder ~/Pictures/screenshots

# Process folder recursively and update markdown references
image-namer folder ~/Documents/notes --recursive --apply --update-refs

Use Cases

  • Knowledge management: Rename screenshots and images in your Obsidian/Notion vaults
  • Photo organization: Generate descriptive names for personal photos
  • Documentation: Rename diagrams and screenshots in your project docs
  • Digital asset management: Organize downloaded images with meaningful names

Getting Started

  1. Install Image Namer - Choose CLI-only or with GUI
  2. Set up your AI provider (Ollama or OpenAI)
  3. Run your first rename - Try CLI or GUI workflow

Philosophy

Image Namer follows these principles:

  • Privacy-first: Default to local models (Ollama) to keep your images private
  • Descriptive over generic: Generate specific, searchable filenames
  • Safe by default: Dry-run mode prevents accidental changes
  • Performance-conscious: Cache results to avoid unnecessary API calls
  • Integration-friendly: Update markdown references to maintain link integrity

Documentation Structure

Requirements

  • Python 3.13 or later
  • An AI provider: Ollama (local) or OpenAI (cloud)

License

MIT License - see LICENSE