You renamed the files to something descriptive, wrote alt text on every image, ticked the image sitemap box in your SEO plugin and waited. Rankings did not move. That is the normal outcome, and it is not because you did the steps badly.
Most WordPress image SEO checklists are ordered by how easy each item is to write about, not by how much it changes. File names are easy to write about. The delivery layer, where the measurable effect actually sits, requires knowing what srcset does and which element is the Largest Contentful Paint, so it usually gets one vague line about compression.
This article sorts the standard advice into three piles: things with a plausible mechanism, things that are neutral, and things that are repeated without evidence. Where WordPress is doing the work, the function, option or filter is named so you can check it in core yourself rather than take my word for it.
What a file name can plausibly do
When a file lands in the media library, WordPress runs the name through sanitize_file_name() in wp-includes/formatting.php, which removes characters that are unsafe in a URL or on disk and collapses runs of whitespace and hyphens into a single hyphen. Then wp_unique_filename() in wp-includes/functions.php resolves collisions by appending -1, -2 and so on. The resulting path, relative to the uploads directory, is stored in the _wp_attached_file post meta row for the attachment, and every generated size is recorded separately in _wp_attachment_metadata.
So the file name becomes part of the image URL, and the URL is one of the few pieces of text that travels with the image everywhere it goes: in a sitemap entry, in a hotlink, in a scraped copy, in a share. DSC_0431.jpg carries nothing. oxford-shirt-collar-detail.jpg carries a little. That is the honest ceiling of the technique: a little.
What a file name cannot do is outweigh the page it sits on. The heading above the image, the paragraph beside it, the alt attribute and the caption all describe the image with far more context than a hyphenated string in a path. Treat the file name as a free, low value signal that costs nothing at upload time and quite a lot afterwards.
Renaming a published file costs more than it returns
This is the part the checklists skip. One upload is not one file. WordPress creates a derivative for every registered size, and on large uploads it also creates a -scaled version that becomes the file the site actually serves. If you want the full picture of that fan out, one upload becomes many files explains which sizes exist and where they come from.
Renaming the original on disk does nothing to those derivatives, and it silently breaks the mapping. The responsive markup is built by wp_calculate_image_srcset(), which reads the sizes array inside _wp_attachment_metadata, where each derivative is a bare file name joined to the uploads path from file. Change the path by hand and the candidates stop resolving. Worse, the editor stores the full URL in the post content, both in classic HTML and in the core image block, so the published markup keeps pointing at a file that is no longer there.
A correct rename of a live image is a URL migration, not a metadata edit. It needs the new file plus all derivatives, an updated attachment record, a search and replace through post content, and a 301 from the old URL to the new one. The old URL may also be sitting in other people’s links, in a CDN cache, in an email newsletter and in an image index, where it has accumulated whatever history it has. Rename before you upload. After publication, leave it alone unless the name is actively wrong.
Alt text is an accessibility field that search engines happen to read
Alt text lives in the _wp_attachment_image_alt post meta row, not in the attachment post itself. wp_get_attachment_image() reads it into the default attribute array, which is exactly three keys wide (src, class and alt) before the dimension and loading attributes are merged in. That is why featured images and theme templates pick alt up automatically. Blocks are different: when you insert an image into a post, the alt is copied into the block markup at that moment, so editing the media library value later does not update posts that already contain the image. For where the value lives, how it differs from the block copy and how to fix a whole library at once, see the deeper piece on alt text in WordPress.
The SEO framing is simple, and it is downstream of the accessibility purpose. Alt is the text alternative shown when the image cannot be rendered or seen. Search engines read it because it is the only reliable, machine readable description of an image that a page is supposed to provide anyway. Write it as the sentence you would say out loud to someone who cannot see the image, in the context of the surrounding paragraph. That sentence usually contains the relevant words already, without any keyword work.
Two rules that people get backwards. A decorative image, a divider, a background texture, a logo already announced by the site title, should have alt="". An empty alt attribute is a deliberate statement that the image carries no information, and screen readers skip it. It is not a missed ranking opportunity. And length is not a virtue: a long alt attribute is read aloud in full, which is a real cost for a real user, in exchange for nothing measurable.
To find the images that have no alt at all, a read only query is faster than clicking through the library. Adjust the table prefix if yours is not wp_.
wp db query "SELECT p.ID, p.post_title
FROM wp_posts p
LEFT JOIN wp_postmeta m
ON m.post_id = p.ID AND m.meta_key = '_wp_attachment_image_alt'
WHERE p.post_type = 'attachment'
AND p.post_mime_type LIKE 'image/%'
AND (m.meta_value IS NULL OR m.meta_value = '')
LIMIT 50;"Captions, titles and descriptions land in different columns
The four fields in the media modal look like a set. They are not. Each one goes to a different place and has a different fate.
- Title becomes
post_titleon the attachment. It powers media library search and the heading of the attachment page. It is not rendered on a normal page, and core does not turn it into atitleattribute on the image. - Caption becomes
post_excerptand is rendered inside afigcaptionelement when the block has one. This is the only one of the four that is genuinely on the page, visible to readers and read as page text. - Description becomes
post_content. It is displayed on the attachment page, which most sites should not be serving at all. On a site with attachment pages disabled, it is a private note. - Alternative text is the post meta row described above, and the only one of the four that reaches assistive technology and crawlers on every page where the image appears.
There is one more mechanism worth knowing, because it explains a lot of junk in media libraries. On upload, wp_read_image_metadata() in wp-admin/includes/image.php reads EXIF and IPTC data out of the file, taking the IPTC headline (2#105) or object name (2#005) as a title and the IPTC caption field (2#120) as a caption. media_handle_upload() then uses those values for post_title and post_excerpt when they are present, with the title skipped if it is purely numeric. That is why photos from an agency or a stock service arrive with a title nobody typed, and occasionally with a caption that appears on the front end unbidden.
So spend the effort on alt everywhere, and on captions where a caption tells the reader something the image does not. The title field is library housekeeping, and filling it with keywords writes into a column no visitor sees in context.
Image sitemaps and what belongs in them
Core sitemaps, at wp-sitemap.xml, ship with exactly three providers in wp-includes/sitemaps/providers/: posts, taxonomies and users. There is no image provider. Image entries come from an SEO plugin, which adds an <image:image> child containing an <image:loc> under the <url> entry for the page the image appears on. The structural fact worth keeping is that images hang off pages in a sitemap. There is no standalone list of image URLs, because an image URL by itself is not a destination.
How the plugin decides which images belong to which page determines what you get. The common approach is to parse the stored post content for img tags and add the featured image. That works for images inserted through the editor. It routinely misses images output at render time by a page builder, images set as CSS background properties, images injected by shortcodes, and images inside reusable blocks or template parts. If an image matters for search and it is not reachable by a content parser, the fix is to put it in the content as a real image element, not to hunt for a sitemap setting.
What does not belong: header logos and decorative theme assets repeated on every URL, and above all attachment pages. WordPress generates a URL for every uploaded file, and each of those pages historically contained one image, a title and nothing else, multiplied by the size of your library. WordPress 6.4 added the wp_attachment_pages_enabled option, and when it is off, redirect_canonical() in wp-includes/canonical.php sends the attachment URL to the file or the parent post instead of rendering a page. New installs get 0 from the default schema. Sites that already existed when 6.4 arrived were given 1 by the upgrade routine, so they kept their attachment pages. Check one attachment URL on your own site before assuming, and if they are live and indexed, turning them off is one of the few pure wins in this entire subject.
Structured data for images
Search engines already read image URLs out of the structured data you publish for other reasons. The image property of Article, Product and Recipe is where an image becomes eligible to appear next to a rich result. If your SEO plugin emits Article schema with the featured image in it, that job is done and there is nothing further to add.
Beyond that, ImageObject carries a small set of licensing properties, among them creator, creditText, copyrightNotice, license and acquireLicensePage. They exist so that licensing information can be surfaced next to an image result, and they are aimed at photographers, agencies and stock libraries. Adding them to the header photo of a blog post achieves nothing, and adding them to an image you do not own is a claim you should not make.
There is no schema property that makes an image rank. If a property is not in schema.org and not listed in the documented requirements for a specific search feature, it is ignored. Invented properties do not create eligibility, they just sit in your JSON, and a validator will flag them.
Delivery is the part that actually moves rankings
Here is the honest hierarchy. File names, captions and alt text are descriptive metadata: they help a machine understand what an image is, and they help a person who cannot see it. Page speed is different in kind, because it is measured on real visits, it feeds into Core Web Vitals, and images are usually both the largest payload on a page and the Largest Contentful Paint element. Every image field you can edit in the media library, added together, changes less than serving the hero image at the right dimensions in the right format.
Three mechanisms carry the weight. The first is dimensions. WordPress builds a srcset from the derivative sizes with wp_calculate_image_srcset() and a sizes attribute with wp_calculate_image_sizes(), and that default value is literally (max-width: Wpx) 100vw, Wpx for an image W pixels wide. It tells the browser to assume the image fills the viewport on anything narrower than the file. In a layout with a narrow content column or a sidebar, that assumption makes the browser pick a candidate one or two steps larger than it needs. The article on how core builds srcset and sizes covers the calculation and how to correct the attribute for your layout.
The second is format and encoder quality. A well encoded WebP or AVIF at the same visual quality is a fraction of the bytes of the JPEG most cameras and stock libraries hand you, and WordPress can convert during upload through the image_editor_output_format filter rather than leaving it to a delivery layer. This is unglamorous, and it is where most of the available savings are.
The third is lazy loading, which is the one people break. Since WordPress 5.5, wp_lazy_loading_enabled() adds loading="lazy" to images by default, and since 6.3 the decision is made per element by wp_get_loading_optimization_attributes() in wp-includes/media.php, which also emits fetchpriority="high" on the element it believes is the Largest Contentful Paint candidate. The number of leading content images that skip lazy loading comes from wp_omit_loading_attr_threshold(), which applies a default of 3, raised from 1 in 6.3. Core is already trying to protect your hero image. The damage usually comes from an optimization plugin that adds its own JavaScript lazy loader to every img on the page, including the one above the fold, which delays that image until scripts have run. The lazy loading article goes through that trap in detail, and the performance piece puts image work in order of payoff against everything else on a slow site.
If your template puts one large image at the top and the rest well below the fold, tightening the threshold to 1 lets the other two start lazy again without touching the image that matters.
// In a child theme functions.php or a small site plugin.
add_filter( 'wp_omit_loading_attr_threshold', function () {
return 1;
} );
Measure before and after on a real page over a real connection. If the Largest Contentful Paint element does not change, the threshold was not your problem and you should take the filter back out.
What image search actually brings
Image search is a real traffic source with a narrow shape. It performs for things people want to look at before they read: products, recipes, diagrams, charts, screenshots of an interface, identification queries where the whole question is what something looks like. It performs badly for stock photography that decorates a text article, because nobody searches for a smiling person at a laptop with the intent of reading your post about invoicing.
The mechanism behind that is worth internalising. An image is found largely through the page it sits on. The surrounding text establishes the subject, and the image inherits the relevance. This is why the same photo used on a well matched page and on a generic page performs differently, and why file name tinkering on a page that is not about the query produces nothing.
The selection criterion is what you publish, not how you tag it. If your images are licensed stock, image search is not a channel worth optimising for. If you produce original photographs, product shots, diagrams or annotated screenshots, do the metadata work carefully on those specific files rather than across ten thousand.
The list is easier to apply to a real image than to remember. Fill in one below, or paste a block of HTML and have every image in it scored.
The weighting is visible rather than hidden behind a number: the file name, the alt text, the dimensions against the display size and the delivery all carry points, and the folklore items carry none, which is the honest way to show that they do not hurt and do not help.
Image SEO check
Check one image, or a whole block of HTML, against the image SEO points that hold up, with the weight of every point in plain sight. The six items at the end are the folklore: they are listed at weight zero because they do not move the score. Nothing is uploaded, the file and the markup are read in this browser tab only.
or press Enter to pick one. Only this tab reads it, the file is never sent anywhere.
The markup is parsed into a document of its own that has no browsing context, so nothing in it loads and nothing in it runs.
| Score | File name | Alt text | First thing to fix |
|---|
| What is checked | Weight | Earned |
|---|---|---|
| Total | 100 | 0 |
These six turn up in every image SEO checklist. None of them changes the score above, whatever you set them to, and none of them does any harm either. They simply do nothing for image search.
| Item | Weight | In your input |
|---|
The weights are a reading of what image search actually uses, not a number handed down by Google. They are printed line by line so you can disagree with them line by line.
The folklore, named plainly
Every item below appears in the tutorials currently ranking for this topic. None of them survives contact with a mechanism.
- Keyword stuffed alt text. Writing
alt="blue widget buy blue widget cheap widgets wordpress"is discouraged in search engine guidance, and it produces a genuinely unpleasant experience for anyone using a screen reader. You are damaging a real accessibility feature to feed a field that is read as a description, not as a keyword list. - Keyword stuffed file names.
best-wordpress-image-seo-plugin-cheap-2026.jpgbuys a fraction of the small benefit a descriptive name buys, and locks you into a URL you cannot change without a redirect. The upside is capped by what a path can express. The downside is permanent. - EXIF and IPTC keywords as a ranking input. WordPress reads a handful of these fields on upload to populate the title and caption, and ignores the rest. Optimization pipelines usually strip the block to save bytes, and any service that re-encodes your images will discard it too. If you want text to be read, the place to put it is the alt attribute or a caption.
- The title attribute helps. Core does not output one on images. Where a theme or plugin adds it, it produces a hover tooltip on desktop, nothing on touch devices, and many screen readers do not announce it in their default configuration. It has no documented role in ranking. The media library Title field is for finding files in the library.
- Every image needs a caption. A caption is body text with one job, saying what the image alone does not. On a decorative image it is noise, and it is noise your readers can see.
- Renaming the whole library for SEO. The highest cost, highest risk item on every checklist, in exchange for the weakest signal in this article. If you have a specific image already bringing traffic from image search, leave its URL exactly where it is.
Symptom and cause
An image disappeared from an older post after you renamed the file. The post content stores the full URL, so the markup still points at the old path. Restore the old file name, or run a search and replace across post content and add a redirect from the old URL.
You fixed the alt text in the media library but the page still shows the old value. The block editor copied the alt into the block markup when the image was inserted. Edit the alt in the block, or use a bulk tool that rewrites post content as well as the attachment meta.
Search Console reports attachment URLs as indexed pages. Attachment pages are still enabled, which is normal on a site that predates WordPress 6.4. Turn them off so core redirects those URLs, and make sure the SEO plugin is not listing them in a sitemap.
Images visible on the page are missing from the image sitemap. The plugin parses stored post content, and those images are produced at render time by a builder, a shortcode or a CSS background. Insert them as real image elements if they need to be discoverable.
Largest Contentful Paint got worse after you installed an image optimization plugin. The plugin is lazy loading the hero image with its own JavaScript, overriding the decision core already made. Exclude above the fold images in the plugin settings, or turn its lazy loading off and let core handle it.
Where the effort pays
Rank the standard WordPress image SEO advice by evidence rather than by ease of writing and the order comes out roughly like this. Serve images at sensible dimensions in a modern format, keep lazy loading away from the Largest Contentful Paint element, and disable attachment pages. Then write alt text that describes the image, because it is the right thing to do for readers and it happens to be the description a crawler uses. Then name new files sensibly at upload time, because it is free. Everything else on the standard checklist is either neutral or a way to spend an afternoon.
The folklore persists because image metadata is easy to audit and easy to score. A plugin can count missing alt attributes and show you a number that goes up. Nothing in that dashboard measures how many bytes your hero image weighs, whether the browser picked a 2048 pixel file for a 700 pixel column, or whether a lazy loading shim held the first image back until the scripts finished. The visible score and the actual lever are not the same thing.
Assume you have already done the obvious steps, since that is usually why you are reading this. The next useful move is not another pass over your file names. It is opening a real page on a real connection, finding which element is the Largest Contentful Paint, checking what the browser downloaded for it and how large that file was, then fixing that one image. Repeat on your three most valuable templates. That is the whole plan, and it takes an afternoon.
