A media library with 4,000 items is the ordinary case, not the extreme one. A site that has published for five years collects images the way a laptop collects screenshots — one at a time, named whatever the camera called them. Image SEO is what you do about that pile.
The mechanics are not complicated. Search engines read a documented and quite short list of signals around an image, and WordPress stores each of them somewhere you can query. What makes this hard is volume.
By the end of this you will know which fields carry weight and where WordPress keeps each one. You will also know what breaks when you rename a file that is already indexed, and how to score a library so you can tell whether the work landed.
What search engines actually read from an image
Google’s image documentation is short and unusually specific. It names the alt attribute, the filename, the content of the page around the image, and structured data — and it says what each one contributes.
Google uses alt text along with computer vision algorithms and the contents of the page to understand the subject matter of the image.
That sentence rules out a lot of received advice. Alt text is one input among several, and the page it sits on is another — an image supports its own description best when it sits on a page about the same subject.
| Signal | Where it lives | What it contributes |
|---|---|---|
| Alt attribute | The alt attribute on the img tag | The text alternative for people using screen readers, and a description Google reads alongside the page content |
| Filename | The image URL | Context before anything renders. Google’s own example is my-new-black-kitten.jpg over IMG00023.JPG |
| Surrounding page text | The page HTML around the image | Subject matter. Google says it extracts this from the content of the page, including captions and image titles |
| Structured data | JSON-LD on the page | Rich result eligibility, and a way to declare which image on the page is the primary one |
| Image sitemap | An XML sitemap extension | Discovery of images a crawler might not otherwise find. Not a ranking input |
| File size and format | The file itself | Page speed. Nothing at all about subject matter |
Compressing a JPEG changes how fast it loads. It changes nothing about what a search engine can tell the image contains. The two get bundled together because both sit under image optimization in most plugin menus, and they are separate jobs done with separate tools. Nothing in this guide makes your files smaller.
The four WordPress fields, and where each one goes
WordPress gives every attachment four text fields — title, caption, alt text and description — and stores them in three different places. The storage is worth knowing, because it decides which of them a crawler ever sees.
| Field | Stored as | Reaches the rendered page |
|---|---|---|
| Alt text |
The _wp_attachment_image_alt post meta |
Yes — as the alt attribute on the img tag |
| Title |
post_title on the attachment post |
Not automatically. The image block has its own separate title attribute field under Advanced |
| Caption |
post_excerpt on the attachment post |
Yes, when the image is inserted with a caption |
| Description |
post_content on the attachment post |
Only on the attachment page |
The description is the field most often filled and least often read. It renders on the attachment page, a URL that plenty of sites redirect away or keep out of the index — in which case nothing written there is visible to anyone.
Every uploaded file gets its own URL in WordPress. Most SEO plugins redirect that URL to the parent post or to the file, and most sites leave the setting on whatever the plugin shipped with. Check which way yours went before you spend an afternoon writing descriptions into it.
Filenames, and the cost of fixing them later
Google’s guidance on filenames is one line: “use filenames that are short, but descriptive”. Its example is my-new-black-kitten.jpg over IMG00023.JPG. None of that is controversial, and almost nobody does it, because the filename is decided at the moment you are least interested in it.
Getting it right before upload costs nothing. Getting it right afterwards costs a URL change, and the URL change is the whole difficulty. I cover both — naming image files before you upload them, and renaming published files without breaking their URLs — in a separate guide.
WordPress does not store one file per image. It writes a separate file for every registered image size — thumbnail, medium, large, plus whatever the theme adds — and each of those has its own URL. Rename the original and every variant moves with it.
An image that has been live for two years may be linked from other sites, cached by a CDN, embedded in a newsletter, or hardcoded into a custom field. A 301 redirect on each old URL keeps all of that working. Without one, every variant is a 404 — and a 404 is something a CDN will happily cache for you.
Redirects are why I treat published and unpublished images as two separate problems. New uploads get named properly on the way in. Published images get renamed only when there is something to redirect them with, and only when the current name is actively bad — a camera default, a name duplicated across dozens of files, or a name in the wrong language.
Alt text, written for screen readers first
Alt text exists so that someone who cannot see the image still gets the information it carries. The relevant standard is WCAG 2.2 success criterion 1.1.1, Non-text Content, at Level A — the lowest conformance level, which means it is not optional for anyone claiming conformance at all.
All non-text content that is presented to the user has a text alternative that serves the equivalent purpose, except for the situations listed below.
The search benefit falls out of the same work. A description accurate enough for a screen reader is a description accurate enough for a crawler, which is why the two goals almost never pull in different directions.
What the standard does not say is how long alt text should be. There is no character limit in 1.1.1, and none anywhere else in WCAG. The 125-character figure repeated across every guide on the subject is a convention with no source in the specification.
I aim for about 110 characters anyway. Not because anything truncates at 110, but because a tight limit forces the description to lead with the subject instead of building up to it. That is a preference, and I would not argue with anyone who ignores it.
What alt text does and does not do
- Gives people using screen readers the information the image carries
- Gives Google a description it reads alongside the content of the page
- Renders as visible text when the image fails to load
- Makes a page WCAG-compliant on its own — 1.1.1 is one criterion out of many
- Helps when it repeats the page title or lists keywords in a row
- Belongs on decorative images, which take an empty alt attribute instead
The empty alt attribute is the part most worth getting right. A decorative image — a divider, a background texture, an icon beside text that already says the same thing — takes alt="" so that a screen reader passes over it. Leaving the attribute off altogether is a different outcome: many screen readers then announce the filename instead.
Captions, titles and descriptions — which are worth the time
Google says it extracts information about the subject matter of the image from the content of the page, including captions and image titles. That is a direct reason to write captions and a thin reason to write titles, because a caption is visible to readers and an attachment title usually is not.
My order on a library where time is finite: alt text and filename on everything, caption where the image needs an on-page explanation, description almost never. The caption is the only one of the four with a second job, and the second job is the one that pays.
Titles earn their keep for a different reason. The Media Library search box searches them, so a library where every title reads Screenshot 2024-03-11 at 14.22.07 is a library you cannot search. Real titles buy back more hours than the SEO argument for the field ever will.
Structured data and image sitemaps
Structured data is where image SEO stops being about the image and starts being about the page it sits on. Product, recipe and article markup each carry an image property, and those decide rich result eligibility. It is a page-level job, not a media library job.
Image sitemaps are the other half, and narrower than they sound. Google describes one as a way of telling it about images it might not otherwise find — images a site reaches with JavaScript, for instance. That is discovery, not ranking, and the distinction matters when someone promises you rankings from a sitemap.
The XML sitemaps added in WordPress 5.5 cover posts, pages, taxonomies and author archives. The core announcement states that image, video and news sitemap extensions are not covered by the feature and are left to plugins. If you want one it comes from your SEO plugin, and it is worth confirming that it is switched on rather than assuming.
How to score an image library
Prioritizing 4,000 images takes a measurement rather than a scroll through the grid. You need a number per image, and that number has to be built from things a machine can check without opening the picture.
The model I use has seven weighted components, and it is the same one Image SEO Optimizer implements — so the weights below are real defaults rather than a sketch. Alt-text presence carries the most at 20 percent, because an empty alt attribute is the one failure that is an accessibility problem and a search problem at the same time.
| Component | Default weight | What it checks |
|---|---|---|
| Alt-text presence | 20% | Whether the alt attribute holds any non-empty value at all |
| Alt-text quality | 15% | Whether the existing alt text uses the saved keywords and sits inside the length and word-count range |
| Title presence | 15% | Whether there is a real attachment title. A WordPress filename-derived default does not count |
| Title quality | 10% | Keyword use and length in the title |
| Filename quality | 15% | Lowercase, hyphenated, in range, and not a camera default such as IMG_2034.jpg |
| Keyword density | 15% | Whether the saved keywords appear across alt text, title and filename rather than in one field only |
| Uniqueness | 10% | How distinct this image’s metadata is from the rest of the library |
Splitting presence from quality is the part that matters. A library where someone bulk-set every alt attribute to Product photo scores full marks on presence and close to nothing on quality and uniqueness. That is the correct answer: the field is filled, and the quality and uniqueness components are where the remaining work shows.
The full weighting, the length thresholds and the way each sub-score is worked out are in how the SEO score is calculated. For the library-wide view — how many images have no alt text at all, what the average score is — there is the media library overview.
Every component here checks whether a field is filled, in range and distinct from its neighbors. None of them checks whether the alt text describes the right picture. An image whose alt text belongs to a different product still scores 100, and only a person reading it catches that.
Doing this at 4,000 images
Do it by hand first. For a few dozen images the manual route beats setting anything up, and the output is better, because you are looking at each picture and deciding what matters about it. Under about 50 images I would not automate any of this.
The arithmetic is what breaks. Reading an image, writing a description, checking the filename and saving takes ninety seconds if you are quick and know the subject. Four thousand images at ninety seconds each is a hundred hours. Nobody finishes that job.
That gap is what I built Image SEO Optimizer for. It sends each image to an AI provider you hold the key for — Anthropic, Google or OpenAI. It writes back alt text, a title, a filename and up to three keywords. The first three are standard WordPress fields, edited the same way you would edit them by hand. The free plugin works one image at a time; the bulk runner is Pro.
The limits matter more than the features. It does not compress anything. There is no undo — the change log records what was written, and reverting is a manual edit. AI calls are rate-limited to 100 per user per hour, so 4,000 images is a background job you check on rather than an afternoon. Nothing it writes makes a page compliant. What the plugin does covers the rest.
check_circle Where generated image metadata earns its place
- check A backlog of thousands of empty alt attributes, where anything accurate beats nothing
- check A catalog that needs one consistent house style across images nobody will re-read
- check Filenames on bulk-imported media, where the alternative is IMG_2034.jpg forever
- check A first draft to edit, which most people work faster from than a blank field
cancel Where it does not
- close Images whose meaning comes from the page rather than the frame — a chart, a diagram, a before-and-after pair
- close Anything where a wrong description is worse than no description, such as medical or legal material
- close Decorative images, which need an empty alt attribute and will get a full description instead unless you exclude them
- close Output nobody reads. Generation varies between runs, so two near-identical products come back worded differently
An order of operations that does not create work
The sequence matters more than the tools. Steps three and four in the wrong order are what turn a tidy-up into a redirect project.
-
1
Count the empty fields first
Filter the media library to images with no alt attribute, then to filenames still carrying a camera or export default. Two numbers, five minutes. They tell you whether this is an afternoon or a project. -
2
Separate decorative images from the rest
Dividers, background textures and icons sitting beside text that says the same thing need an empty alt attribute, not a description. Decide this before anything writes to the field, because an automated pass will describe them. -
3
Name new files before you upload them
A filename set at upload costs nothing and never needs a redirect. Short, lowercase, hyphenated, describing the subject rather than the project — image-sitemap-report.jpg, not final_v3_EXPORT.jpg. -
4
Rename published files only with redirects in place
Every size variant needs its own 301. Confirm that whatever performs the rename writes one per variant and rewrites the references in post content, then purge the CDN afterwards. -
5
Write alt text, then read it back without the image
If the sentence does not tell you what the picture shows, it is not finished. This step catches the description that is accurate about the frame and useless on the page. -
6
Wait a crawl cycle, then look at Search Console
Filter the Performance report to the Image search type and compare against the period before the change. Expect weeks, and expect to read the signal across the library rather than on any single image.
Terms used above
- Size variant
- WordPress writes a separate file for every registered image size at upload — thumbnail, medium, large, plus whatever the theme adds. Each one has its own filename and its own URL.
- Attachment page
- The single-post page WordPress creates for every uploaded file, at its own URL. Many SEO plugins redirect it to the parent post or to the file itself.
- 301 redirect
- A permanent redirect. It tells browsers and crawlers that a URL has moved for good, and carries over what the old URL had accumulated.
- Image sitemap
- An XML sitemap extension listing the images on each page. It helps a crawler find images it would otherwise miss, particularly ones loaded by JavaScript.
- srcset
- The attribute listing several size variants of one image so a browser can pick the right one for the screen. Every URL in it is a real file that a rename has to account for.
Frequently asked questions
One thing to do after reading this: filter your media library to the images with no alt attribute at all, and count them. Every decision above gets easier once that number exists, and it is almost always larger than people expect.
Image SEO Optimizer Pro
Fill the fields without breaking the URLs
Image SEO Optimizer is free on wordpress.org. Bring an Anthropic, Google or OpenAI key, and every filename change is 301-redirected on each size variant.
Personal
Single-site license – ideal for personal blogs or small websites.
- check_circle 1 Site License
- check_circle Bulk Processing
- check_circle Image Context Generation
- check_circle Real-time Upload Optimization
- check_circle Best-in-Class AI Models
Freelancer
License for up to 10 sites – ideal for freelancers and developers.
- check_circle 10 Sites License
- check_circle Bulk Processing
- check_circle Image Context Generation
- check_circle Real-time Upload Optimization
- check_circle Best-in-Class AI Models
Agency
Unlimited Sites – ideal for digital agencies and corporations.
- check_circle Unlimited Sites
- check_circle Bulk Processing
- check_circle Image Context Generation
- check_circle Real-time Upload Optimization
- check_circle Best-in-Class AI Models
Alt text SEO: screen readers first, search engines second
The search benefit of alt text is a byproduct of writing a real text alternative. What WCAG asks for, where WordPress keeps…
SEO image naming: how to rename WordPress files safely
Renaming a published image changes one URL per registered size. What a rename moves, which references get rewritten, which need a 301,…