AI Image Renamer is a small Python script you don’t want to miss. AI—like any other tool—exists to make our lives easier, to solve problems, or to take over tasks that we’re simply too lazy for. A quick search on GitHub for AI-related scripts or apps, though, often doesn’t seem to follow that pattern. In fact, it’s the complete opposite: quite a few tools using AI in one form or another solve problems that nobody has.
I, on the other hand, do have a problem. Or let’s say did, because I created my own way to deal with this.
What The F– Filename?!
I often use the macOS app IconJar, which is essentially a library that stores, well, icons. The problem I kept facing was that most, if not all, of the icon sets I downloaded were filled with image files that had names completely unrelated to the image itself (think: 1637932675_n.jpg). Using the search bar to search for a specific icon was, therefore, a rather fruitless endeavor since IconJar or even the search function on your OS looks at the filename of each icon.
There, a problem. A problem that AI can fix with ease. And since all those companies are basically in a friendly (well, mostly friendly) arms race with their big-language models (LLMs)—kind of like the Cold War but with more computers—there’s no shortage of models you can use to solve this problem.
Let AI do the Lazy Work
And because wasting days looking at and renaming thousands of icons just to be able to find them more easily, I created “AI Image Renamer,” a Python script that does this for me. The LLM behind, Llama Maverick, has a “vision” feature that allows it to “look” at an image, know what it shows, and with the right prompt, you can use this information to generate a filename that actually makes sense.
With AI Image Renamer, I built a simple CLI tool that lets you do all this with one command:
rename-images --words 5 file-1.jpg file-2.png file-3.webpThat’s it. The command sends an encrypted version of the image file to the fastest AI provider of open-source LLMs, Groq, and creates a new descriptive filename like this:
man-with-coconut-on-beach.jpgThe --words or -w argument is optional and defaults to 5. You can use it to tell the script how many keywords it should use to describe your image. I found 5-8 keywords to be the best solution. Not overly long but long enough to let every search function find what you’re looking for.
Free and Easy to Install
AI Image Renamer is, of course, open source and can be downloaded through the repository or through pip, the package manager for Python that hosts its scripts on PyPi.org. Getting the source code via Git (GitHub, GitLab) requires you to install a virtual environment, which lets you use the image-renamer.py file to run the above-mentioned command. Add --help to see the full usage, or check the documentation.
Don’t forget to add your Groq API key to your environment variable. Here’s how.
A more elegant way is pipx. With pipx, you can simply install the script through pipx install ai-image-renamer and then use it system-wide without colliding with your system’s Python environment.
I found it so helpful that I integrated it into my context menu. Now, whenever I have one of these cryptic filenames, I right-click the file, choose “Quick Actions,” and then “AI Rename.” That’s all.
This is how it looks on macOS 26:
I mentioned Groq, didn’t I? Groq, being so fast and everything, still lets you create a free API key that you must use for AI Image Renamer to work, but it comes with limitations. Namely:
- each image must not exceed 4 MB,
- each image must have a resolution less than 33 megapixels (e.g., 7680×4320),
- and you can process up to 5 images per command.
Unless you plan to rename your entire media library, this has always been enough for me.
Conclusion
Renaming images manually sucks. AI Image Renamer, written in Python, lets you rename images to a more descriptive version based on what the image shows. All for free, with minimal setup done in under five minutes.
It helped me so much that I created a VitePress documentation site for AI Image Renamer, detailed installation and usage instructions included. It also shows you how to create the Quick Action that makes things even more comfortable.
There, problem solved. Thanks, AI.