image-namer 2.0.0

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

Image Namer

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

Transform generic filenames like IMG_2347.jpg into descriptive names like golden-retriever-puppy--running-in-park.jpg using AI vision analysis.

Features

• 🤖 AI-powered naming using Ollama (local) or OpenAI (cloud)
• 🖥️ Dual interface - Choose command-line (CLI) or graphical (GUI) workflow
• 🏠 Local-first with Ollama for privacy
• ⚡ Intelligent caching to avoid redundant API calls
• 🔄 Idempotent - won't rename already-suitable files
• 📁 Batch processing with recursive folder support
• 📝 Markdown reference updates for Obsidian and standard markdown
• 🔍 Dry-run mode to preview changes safely (CLI)
• ✏️ Manual editing via table double-click (GUI)
• 🎯 Smart collision handling

Quick Start

Installation

Install Image Namer using pipx for a clean, isolated installation:

# Install pipx (if needed)
brew install pipx  # macOS
# or: python3 -m pip install --user pipx

# CLI only (lightweight)
pipx install image-namer

# With GUI (includes Qt6 interface)
pipx install 'image-namer[gui]'

# Verify installation
image-namer --help         # CLI commands
image-namer-ui             # Launch GUI (if installed with [gui])

Why pipx? It installs Python CLI tools in isolated environments, preventing dependency conflicts with other projects.

Setup AI Provider

Image Namer requires an AI vision model. Choose one:

Option 1: Ollama (Recommended - Free & Local)

# Install from https://ollama.com
ollama pull gemma3:27b

Option 2: OpenAI (Cloud - Requires API Key)

export OPENAI_API_KEY='sk-proj-...'

Basic Usage

Command Line (CLI)

# Preview rename (dry-run)
image-namer file photo.jpg

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

# Process entire folder
image-namer folder ~/Pictures/screenshots --apply

# Update markdown references
image-namer folder ~/Documents/notes/images --apply --update-refs

Graphical Interface (GUI)

# Launch GUI application
image-namer-ui

# Then use the visual workflow:
# 1. Click "Open Folder" to select directory
# 2. Click "Process" to analyze images
# 3. Review/edit names in table (double-click to edit)
# 4. Click "Apply" to rename files

Documentation

📚 Full Documentation (comprehensive guides and reference)

Quick links:

• Installation Guide - Detailed setup instructions
• Getting Started - Your first rename
• How-To Guides - Step-by-step workflows
• CLI Reference - Complete command docs

Development

Setup

# Clone repository
git clone https://github.com/svetzal/image-namer.git
cd image-namer

# Install with development dependencies (using uv)
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e ".[dev,gui]"  # Includes GUI for testing

# Or with pip
pip install -e ".[dev,gui]"

Testing

pytest                    # Run all tests with coverage
pytest -v --no-cov       # Verbose without coverage
flake8 src               # Lint code

Documentation

# Install docs dependencies (included in [dev])
pip install -e ".[dev]"

# Serve docs locally
mkdocs serve

# Build docs locally
mkdocs build

Note: Documentation is automatically deployed to GitHub Pages when a new release is published. See docs/GITHUB_PAGES_SETUP.md for details.

Requirements

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

License

MIT License - see LICENSE

Project Status

🎉 Version 2.0.0 - Production Ready with GUI

Complete Features

✅ Core Functionality

• Single file and batch folder renaming with AI vision analysis
• Smart pre-flight assessment to skip already-suitable files
• Intelligent caching system (dramatically reduces LLM calls)
• Idempotent operations (won't rename if name already matches content)

✅ Dual Interface

• CLI: Command-line workflow with dry-run/apply modes
• GUI: Qt6 graphical interface with visual preview and editing

✅ Markdown Integration

• Automatic reference updates in standard Markdown and Obsidian
• Preserves alt text and aliases
• URL-encoded path handling

✅ AI Providers

• Ollama (local, privacy-focused, default)
• OpenAI (cloud-based)
• Easy provider switching via CLI or environment variables

✅ Developer-Friendly

• Comprehensive tests with high coverage
• Type-safe with Pydantic models
• Well-documented code and APIs
• Flake8 compliant

What's Not Included (By Design)

• Video or PDF processing (images only)
• Multi-language filename support (English slugs)

See CHANGELOG.md for detailed release notes.