usdigitalmarketingindex.com SEO
How can image URLs retain search visibility during a media library migration?
Updated November 15, 2026
By treating every image file as a URL with its own history, mapping each old image address to its new one, redirecting the old to the new permanently, and updating the pages that embed the images so their markup, alt text, and surrounding context carry over unchanged. An image in search results is tied to two things: the address of the file and the page it is embedded in. A media migration can break either. If the files move and the old addresses return errors, the images Google knows no longer exist. If the pages change how they reference the images, the association is rebuilt from nothing. Google’s site move guidance names this directly, asking that move plans include the URLs of embedded content such as images, and that these be redirected like pages (Google’s guidance on site moves with URL changes).
Inventorying old image URLs
Images are easy to miss in a migration, because they are not in the page list. Build their inventory separately.
| Source | Gives |
|---|---|
| Crawl of the old site, with image extraction | Every image URL referenced in page HTML, with the embedding page and alt text |
| Media library export from the CMS | Every stored file, including unused ones |
| Server or CDN logs | Image URLs requested, including from other sites and from image search |
| Search Console performance report, search type set to image | Pages receiving image search clicks |
| Sitemaps with image entries | Declared images |
| CSS files | Background images |
| Structured data and social tags | Images named in markup |
Record for each image: the file URL, the pages embedding it, its alt text, its dimensions, the generated size variants, and whether it has image search clicks or external requests.
Size variants multiply the count. One uploaded photograph may exist at five addresses, and each is a URL that pages and other sites may reference.
Image-specific redirects
A media URL mapping sample, for a move from a CMS uploads folder to a media host:
| Old image URL | New image URL | Action |
|---|---|---|
| https://www.example.com/wp-content/uploads/2023/04/boiler-gauge.jpg | https://media.example.com/images/2023/04/boiler-gauge.jpg | 301 |
| https://www.example.com/wp-content/uploads/2023/04/boiler-gauge-768×512.jpg | https://media.example.com/images/2023/04/boiler-gauge.jpg?w=768 | 301 |
| https://www.example.com/wp-content/uploads/2021/11/radiator-valve.png | https://media.example.com/images/2021/11/radiator-valve.png | 301 |
| https://www.example.com/wp-content/uploads/2019/02/old-banner.jpg | None; image retired | 404 or 410 |
| https://www.example.com/images/logo.svg | Unchanged | None |
Principles:
- Keep file names. A migration that renames every file to a hash discards descriptive names and makes mapping harder. If the new system must rename, the map records both.
- Preserve the path pattern where possible, so one rule covers the library.
- Redirect permanently, with a server-side redirect, in one hop.
- Redirect every size variant, to the equivalent variant or to the original.
- Redirects must be answered by the old host. If the old uploads path is switched off without rules in place, every old image URL becomes an error.
- Keep the redirects. The guidance says to keep site move redirects for as long as possible, generally at least a year.
The better option, where the platform allows, is not to change image URLs at all. A reverse proxy or CDN in front of the old paths can serve files from the new storage at the same addresses. No redirect is then needed, and nothing has to be rediscovered.
If images move to a different hostname, such as a CDN domain, check that the new host allows crawling. A robots.txt file on the media host that disallows everything hides every image served from it.
Page markup and alt continuity
The page side of the association must survive too.
| Element | Requirement |
|---|---|
| The img element | Still present in the served HTML, with a <!–INLINECODE0–> a crawler can fetch |
| <!–INLINECODE1–> | The new image URL, directly, not through the redirect |
| Alt text | Carried over exactly for each image |
| Captions and surrounding text | Unchanged |
| File placement | The image appears on the same page as before, near the same text |
| Responsive markup | <!–INLINECODE2–> and <!–INLINECODE3–> name working URLs |
| Lazy loading | Implemented so the image URL is in the HTML, not only supplied by script on scroll |
| Dimensions | Width and height attributes retained |
| Structured data images | Updated to new URLs |
| Open Graph and social images | Updated |
| Image sitemap entries | Updated to new URLs |
| CSS backgrounds | Updated |
Alt text is the item at risk. Where a system stores it in the media library, attached to the file and not in the article, a file migration can leave it behind. Export it with the files and confirm on the new site that each image still has its text.
Check what the new system does to the files themselves: format conversion, recompression, resizing, and stripping of embedded data. A change of format changes the URL’s extension, which is one more mapping to record.
Search verification
A QA checklist for broken images:
| Check | Method | Pass condition |
|---|---|---|
| Every old image URL resolves | Request each from the inventory | 301 to the mapped URL, final status 200, content type an image |
| No image errors on pages | Crawl the new site; list image requests by status | No 404 or 5xx |
| No redirected <!–INLINECODE4–> values | Same crawl | Pages reference final URLs |
| Alt text parity | Compare alt text per image, old crawl against new | Equal |
| Images in served HTML | Fetch pages without JavaScript; list img elements | Present |
| Media host crawlable | Fetch robots.txt on the image host | Does not block image paths |
| Mixed content | Check image URLs' scheme | HTTPS |
| Size variants | Request a sample of variant URLs | Resolve |
| Hotlinked and external references | Request the old URLs most requested by other sites, from logs | Redirect and load |
| Rendered check | URL Inspection on pages with important images; view the screenshot and resources | Images loaded |
| Caching and headers | Inspect response headers on new image URLs | Cacheable; correct content type |
| File integrity | Open a sample of images | Not corrupted; expected dimensions |
After launch:
| Indicator | Source | Expectation |
|---|---|---|
| Image search clicks and impressions | Performance report, search type image, by page | Continuity, allowing for a transition |
| Not-found errors for image paths | Server and CDN logs | None for mapped URLs |
| Requests to old image URLs | Logs | Continuing, and answered by redirects |
| Crawl activity on the media host | Crawl stats, if the host is verified as a property | Images being fetched |
Expect a transition for images whose URLs changed. Google has to fetch the old address, follow the redirect, and associate the new file with the page. Google’s site move guidance describes ranking fluctuation during a move as temporary and normal, and gives no figure for images in particular. Where URLs were kept unchanged, there is nothing to transition.
Verify the image host in Search Console if it is a separate hostname, so its crawl data is visible.
Keep the mapping file with the migration records.
Where the new media system serves images from a different domain, the question of whether and how to list them in a sitemap arises, and is covered in the guide to when an image sitemap should include assets hosted on a separate CDN.
The rule: keep image URLs unchanged if you can; if you cannot, map and permanently redirect every file and variant, and carry each image’s alt text and page context across intact.
Add your comment to this answer