SEO image naming: how to rename WordPress files safely

Most media libraries carry two kinds of bad filename. There is IMG_2034.jpg, straight off a camera, and there is final_v3_EXPORT.jpg, straight off somebody’s desktop. SEO image naming is mostly the work of not adding any more of them, and it is nearly free right up until the file is published.

After that it stops being free. Renaming a published image changes a live URL, and WordPress does not keep one file per image — it writes one for every registered size, plus a scaled original on large uploads. Each of those is a URL something may already be requesting.

The answer here is mechanical rather than editorial. By the end you will know what a rename touches on disk, which URLs need a 301 and which never get one. You will also know what no rewrite pass reaches, and when leaving a bad filename alone is the right call.

What SEO image naming actually buys you

Google’s guidance on filenames is one line long. Its image documentation asks for filenames that are short, but descriptive, and its worked example is my-new-black-kitten.jpg over IMG00023.JPG (Google Search Central, checked 2026-08-10).

That is the whole documented claim, and it sits beside three other things the same page names: the alt attribute, the content of the page around the image, and structured data. A filename is one input among four, read in the absence of anything better.

Naming a file before you upload it

Write the name for the URL it becomes. Lowercase ASCII letters, numbers and hyphens; no capitals, no underscores, no accented characters; the words that describe the subject first and the ones that describe the project not at all.

I score filenames against 40 to 60 characters and 3 to 6 hyphen-separated words. No search engine publishes a limit, so those are a working convention rather than a rule. A name that fits them is almost always descriptive without becoming a sentence.

Drop the filler. Words like with, from, the, and, for, in, on and of read as noise in a slug, and they push the descriptive words out of the first few characters. Prefer chocolate-cake-cream-plate-dessert over chocolate-cake-with-cream-on-a-plate.

For a site publishing in a non-Latin script, transliterate rather than translate — changcheng rather than great-wall for a Chinese-language site writing about 长城. The URL stays legible to the people who search in that language, and stays ASCII for every cache and log that handles it.

When renaming a published file is worth it

Rename a published image when the current name is not descriptive, not when it is merely unimpressive. Not descriptive means a camera or export default, one name repeated across dozens of files, a language the site does not publish in, or a name that reveals something better kept private — a client, a price, an unreleased product.

Leave the rest alone. A file that is already earning image impressions has a URL with history, and a rename trades that history for a redirect you now have to keep alive. An indexed URL with a mediocre name usually beats a perfect name on a URL that just moved.

Filenames are the cheapest field to get right and the most expensive to change, which puts them in an odd position against alt text, titles and captions. What each of the four is read for is in image SEO beyond filenames.

What a rename actually moves

On disk and in the database a rename is a short sequence. The file moves through the WordPress filesystem layer, the attachment record is repointed at the new path, and the attachment slug is rewritten to the new stem. Then the size variants are regenerated from the renamed file and the old variant files are deleted.

fullscreen

Two consequences fall out of that and neither is obvious. The regenerated variants are new files, so a thumbnail somebody hand-cropped comes back as an automatic crop. And because the attachment slug moves, the attachment page URL moves with it — that one is not an image URL, so an image redirect never covers it.

Every URL a rename has to account for

The URL set is larger than the file set. A correct map covers four kinds of URL: the canonical attachment URL, the upload-relative form of the same file, one URL per registered size, and the scaled original on a large upload.

The count varies by site: registered sizes come from core, from the theme, and from any plugin that adds one, so the same rename produces a different number of rows on two sites. That is the reason not to write a redirect list by hand from memory.

fullscreen

Then the redirects: one 301 per old URL, each pointing at the variant that replaced it. Sending every old size to the full-size file is the shortcut that reappears later as a 2 MB image in a thumbnail slot. The map, the rewrite pass and the redirect row are documented in how renaming and 301 redirects work.

How the redirect gets served, and when it does not

A redirect row does its job only when something reads it. In WordPress that happens on template_redirect, so the request has to reach PHP before any lookup occurs. This is the boundary most people never check, and the web server decides it rather than the plugin.

An Apache install using the standard WordPress rewrite rules hands a request for a missing file to index.php, so WordPress runs and the redirect fires. Several common Nginx configurations serve the uploads directory directly and answer a missing file with their own 404, and PHP is never invoked. Request one old thumbnail URL with curl before you trust the mechanism across a batch.

In Image SEO Optimizer the rows live in a table named for the site prefix plus infyp_redirects, the lookup runs only for request paths under the uploads directory, and the response is a 301 with a one-week Cache-Control header. Capture is on by default and can be switched off — with it off the rename still happens and the old URLs 404.

Rows carry an expiry, and the default is 12 months. The other choices are 6 months, 24 months and never, and a daily job marks anything past its date as expired so it stops serving. An expiry delays the failure rather than removing it: the 404 arrives a year later, on a URL nobody is watching. If the images are linked from anywhere outside your control, set it to never.

Rename the same image twice and the first row has to be rewritten to point at the final URL, or you have built a redirect chain by hand. Which rows exist, how often each was hit and when, are listed in the 301 redirects manager. A row still showing zero hits a month later tells you the old URL had nothing pointing at it.

The references a rewrite reaches, and the ones it does not

A 301 keeps old URLs working. It does not clean your content, and a page full of redirected image URLs pays an extra round trip per image. The rewrite pass is what stops that, and it is the half people forget.

The pass replaces the filename stem rather than the whole URL, which is how every size variant gets caught in one operation. It also has to handle the encoded forms of that string: percent-encoded in some markup, slash-escaped inside page-builder JSON.

Six builders are covered by adapters — Gutenberg always, then Elementor, Visual Composer, WPBakery, Uncode and Divi when each is active. Elementor keeps its layout as JSON in post meta, so that adapter decodes the data, replaces inside it and re-encodes it, rather than swapping strings across serialized text.

fullscreen

Three kinds of reference stay out of reach: URLs hard-coded in theme PHP, anything held by a CDN or a full-page cache, and every reference outside the install — a newsletter sent last year, a partner site, a scraped copy. The first is a grep, the second a purge, the third is what the redirect is for.

Doing this by hand, and where it stops

The manual route is real work, not a straw man, and for a handful of images it is the right choice. Rename the file on disk, repoint the attachment record and regenerate the sizes. Then run a dry-run search and replace on the filename stem so the variants come back too, add the redirect rules, and purge the caches in front of the site.

The arithmetic is where the manual route stops. Finding references, renaming, regenerating, rewriting six kinds of storage, writing a 301 per variant and re-checking takes long enough that nobody does it twice. That gap is what I built Image SEO Optimizer for: it generates the name from the image on your own Anthropic, Google or OpenAI key, renames the file, rewrites what it can reach and writes the redirect rows in one operation.

The limits are worth stating flatly. It renames one image at a time — the bulk runner is Pro. It handles jpg, jpeg, png, webp and gif and refuses everything else, SVG included. It will not overwrite an existing file, and it rejects any name outside letters, numbers, dots, underscores and hyphens. It does not purge your CDN, read your theme’s PHP, or compress anything.

Generated names vary between runs, which makes reviewing a filename before the rename runs a real step rather than a formality. Wiring it into something larger comes down to two filters. infyp_pre_file_rename returns false to cancel a rename outright. infyp_filename_url_map adds URLs — a CDN hostname, a custom size — to the map that the rewrite and the redirect rows are built from.

One thing to do after reading this: filter your media library to files still carrying a camera or export default, then check how many of them appear in more than one post. That second number decides whether this is an afternoon or a project, and almost nobody has it.

Written by Christian Ehler

I'm a WordPress developer and technical SEO — in search since 2010, currently traveling the world and working from wherever the coffee and wifi hold up. My focus is building WordPress apps on top of AI: automating the daily SEO workflows nobody has time for and preparing sites in depth for how AI-driven search reads the web. InfyPress is the first piece of that.

article 3 articles

language