GitHub - KevinColemanInc/img_rename

Ollama Image Renamer

Rename images using an Ollama model prompt. The script validates image bytes before sending the file to Ollama, generates a short name, and renames the file while keeping the original extension.

Requirements

• Python 3.9+
• An Ollama server running locally at http://localhost:11434
• Pillow for image validation
• uv (https://github.com/astral-sh/uv)

Install

Usage

uv run img-rename /path/to/images

Run via bash wrapper (no activation needed):

./img-rename /path/to/images

By default it uses the gemma3:12b model and a simple naming prompt.

Options

• dir Directory to scan
• --model Ollama model name (default: gemma3:12b)
• --prompt Custom prompt for naming

Example with custom model:

uv run img-rename ./images --model gemma3:12b

Example with a custom prompt:

uv run img-rename ./images --prompt "Return 2-4 English words describing the image."

Example combining wrapper + options:

./img-rename ./images --model gemma3:12b --prompt "English, short, descriptive filename."

Notes

• The script checks file bytes with Pillow’s verify(); only valid images are processed.
• Filenames are made URL-friendly: spaces become _, other non-alphanumeric characters are stripped.
• If a name already exists, the script appends _2, _3, etc.

Troubleshooting

• If you see Missing dependency: Pillow, run uv sync.
• If Ollama is not running, start it or adjust the endpoint in rename_images.py.