Photonamer: Autonomous AI Image File Renamer for Apple Silicon Macs

PhotoNamer is a fast, privacy-first CLI tool that uses local a Vision-Language Model (specifically Qwen2.5-VL) to analyze your photos and automatically rename them based on their visual composition, lighting, and mood.

Built specifically for Apple Silicon using the MLX framework, it processes heavy RAW and JPEG files entirely offline—meaning your personal photos never leave your Mac.

Features

• True Visual Understanding: Powered by Qwen2.5-VL, it looks at the image and extracts the subject, mood, lighting, and photographic principles.
• 100% Local & Private: No API keys, no cloud uploads, no subscriptions. Everything runs on your own hardware.
• Apple Silicon Optimized: Uses Apple's native MLX framework for unified memory processing, keeping RAM usage perfectly stable even when processing thousands of photos.
• Fail-Safe Dry Runs: By default, the app runs in "Preview Mode" so you can see exactly how files will be renamed before altering your file system.
• Highly Customizable: Interactive wizard lets you build your naming template on the fly and choose your preferred casing (PascalCase, snake_case, UPPERCASE, lowercase).

Installation

Prerequisites

• A Mac with an Apple Silicon chip (M1/M2/M3/M4), at least 16GB of RAM is recommended.
• Python 3.10 or newer.

For Photographers & End-Users (Recommended)

The safest and easiest way to install PhotoNamer globally is using pipx. This ensures the heavy AI dependencies don't conflict with your Mac's system files.

1. Install pipx via Homebrew (if you haven't already):

   brew install pipx
   pipx ensurepath
   

2. Install the app via pipx:

   pipx install photonamer
   

Alternative: pip

If you're already working inside a virtual environment:

pip install photonamer

For Developers

If you want to modify the source code or contribute, install it in editable mode:

git clone https://github.com/Kevo-03/Automatic-Photo-Namer.git
cd Automatic-Photo-Namer
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Uninstallation

1. Remove the Package

If you installed with pipx:

pipx uninstall photonamer

If you installed with pip:

pip uninstall photonamer

2. Remove the Downloaded AI Model

PhotoNamer downloads a ~5 GB model to the Hugging Face cache on first run. Uninstalling the package does not delete these cached model files automatically.

To remove only the PhotoNamer model while keeping other Hugging Face models intact:

rm -rf ~/.cache/huggingface/hub/models--mlx-community--Qwen2.5-VL-7B-Instruct-4bit

To remove the entire Hugging Face cache (only do this if no other apps depend on it):

rm -rf ~/.cache/huggingface

Usage

Navigate to any folder containing your photos (.jpg, .jpeg, .png, .nef) and simply run the command:

photonamer

[!NOTE] First Run: On the very first launch, PhotoNamer will download the ~5 GB AI model from Hugging Face. This is a one-time process and may take several minutes depending on your connection. The CLI will prompt you with a message suggesting you create a free Hugging Face access token for faster, authenticated downloads. Subsequent runs will use the cached model instantly.

The interactive wizard will guide you through the process:

1. Fields: Choose what information you want in the filename (Options: date, subject, mood, lighting, principle).
2. Separator: Choose how fields are connected (e.g., _ or -).
3. Casing Style: Format the text (pascal, snake, upper, lower).
4. Execution: Confirm if you want a safe dry-run (Preview) or a live execution.

Running with Flags

You can skip the interactive wizard entirely by passing options as flags. Any flag you provide will not be prompted for—only missing options trigger a prompt.

# Skip the wizard completely
photonamer --fields "date,subject,mood" --sep _ --casing pascal --execute

# Skip only some prompts (remaining options will still be prompted)
photonamer --sep - --casing kebab

Dry Run Example

Architecture Under the Hood

• Engine: Apple mlx-vlm for hardware-accelerated inference.
• Model: Qwen/Qwen2.5-VL-3B-Instruct for optimal speed-to-accuracy ratio.
• Memory Management: Implements isolated sequential processing. The 5GB AI model loads into unified memory exactly once, and Python's garbage collector destroys individual image tensors post-inference, preventing thermal throttling or RAM overflow during massive batch jobs.
• CLI Framework: Built with Typer and Rich for a beautiful, type-safe terminal experience.