Skip to main content

Virtual Image URLs

How Live Mode gives every page its own image filename without copying files, and how the Virtual Image URLs setting decides when to use it.

Written by Niklas

This article covers images on Live Mode pages: how each page gets its own image filename without a copy of the file, and the setting that decides when that happens. If you haven't used Live Mode yet, start with What is Live Mode?.

When you use image processing with a placeholder in the filename, for example a source file column hero_image.jpg with the value plumber-{city}.jpg, Classic Mode makes a real copy of the source image for every page: one file, one set of thumbnails and one media library entry per page. That is what gives each page its own image filename and alt text for image SEO. It is also exactly the kind of per-page bulk Live Mode is meant to avoid.

Live Mode keeps the source image as a single file in your media library. Each Live page serves that same file under its own filename through a URL LPagery owns, called a Virtual Image URL:

https://example.com/lpagery-img/24952/plumber-austin.jpg

1. What a Virtual Image URL gives you

  • The filename and the alt and title text are substituted per page, just like in Classic Mode.

  • Responsive sizes (srcset) work. Each thumbnail size is served under the page's filename too.

  • Nothing is copied: no extra files and no extra media library entries, however many pages you generate.

  • Browsers, CDNs and caching layers can cache these images for one day.

Only the page's own address is virtual. The file behind it is the source image in your media library, so replacing that source changes every page that uses it.

2. What stays the same as Classic

Image URLs in a cell, for example https://example.com/photos/austin.jpg, are still downloaded and stored as real attachments. Those are different files per row.

Plain filenames without a placeholder, for example hero.jpg, still reference the existing media library image.

The featured image of a Live page points at the source image.

In lists such as archives, search results and Views, Live pages show the shared source file with their own alt text. Only the page itself uses the per-page filename.

3. The "Virtual Image URLs" setting

Serving an image through WordPress instead of straight from the web server has a cost: every uncached image request boots WordPress. Behind a CDN or caching layer that absorbs repeat requests, that cost is paid once per image and then cached. On slow hosting without one, it can noticeably slow image loads on cold page views.

So per-page image filenames are controlled by one site-wide switch in Settings: Virtual Image URLs.

When the switch is on, Live pages use per-page image filenames as described above. This works best with a CDN or caching layer.

When the switch is off (the default), Live pages use the shared source file's own URL, served directly by your web server. Alt and title text are still substituted per page. Only the per-page filename is missing.

Both states show correct images. Flipping the setting never regenerates pages. It only changes what new page renders emit, and LPagery purges cached Live pages so the change shows immediately.

4. LPagery picks the initial value for you

After activation, LPagery fetches a tiny test image through your site's public address a few times and checks whether a cache in front of your site answered any of the repeats. If one did, the setting is switched on. If every request reached WordPress, it stays off. The line under the switch tells you what was found:

  • A CDN or caching layer was detected on this site. Detection found a cache in front of your site and switched the setting on.

  • No CDN or caching layer was detected on this site. Every test request reached WordPress, so the setting was left off.

  • The setting was saved manually before detection completed. You chose a value yourself, and detection won't override it.

  • Automatic detection couldn't reach a result on this site. Detection gave up after several inconclusive attempts, so the setting stays off.

  • Detection hasn't completed yet. Detection is scheduled but hasn't run.

Your own choice always wins: once you save the setting, detection never changes it again. Run detection again re-runs the check on demand, which is useful right after you've added a CDN. If you switch the setting on without a positive detection, an amber note under the switch reminds you that every image on a Live Mode page is then served through WordPress on each request.

5. Requirements

Virtual Image URLs need pretty permalinks: any permalink structure other than "Plain" in Settings -> Permalinks. With plain permalinks, Live pages fall back to the shared source URLs and LPagery shows a warning in its admin screens.

The web server must also let WordPress answer image URLs. LPagery checks this by fetching one real Virtual Image URL from your site. If the server answers with a 404 or a non-image (typically a rule that serves every .jpg or .png path as a static file), Live pages fall back to the shared source URLs and LPagery shows a warning naming the reason. The check recovers on its own once the server answers correctly.

Falling back never loses anything. Alt and title text stay substituted, and per-page filenames return as soon as the requirement is met.

Troubleshooting

My Live pages show images, but the filenames aren't per page

That is the shared-source render, and it is usually deliberate: the Virtual Image URLs switch in Settings is off, which is the default when no CDN or caching layer was detected. Switch it on if your site sits behind a CDN or caching layer.

If the switch is on and filenames are still shared, LPagery is falling back on purpose and shows a warning in its admin screens naming the reason. Either pretty permalinks are disabled (pick any structure other than Plain in Settings -> Permalinks), or the Endpoint Health check failed, which means your server is intercepting image URLs before WordPress can serve them. In that case, contact support with your hosting details.

Images on Live pages load slowly

Turn Virtual Image URLs off in Settings unless a CDN or caching layer sits in front of your site. Images then come straight from the web server, and alt and title text stay substituted.

I added a CDN after installing LPagery

Open Settings and click Run detection again under Virtual Image URLs. If you had already saved the setting yourself, detection reports what it found but leaves your choice alone, so switch it on manually.

A Virtual Image URL returns 404

Virtual Image URLs only exist for the images a Live page actually uses. Any other path under /lpagery-img/ is a 404 by design. If a URL that the page itself emits returns 404, either LPagery is deactivated (see Create and switch Live Mode Page Sets) or the server rule described under Requirements is intercepting it.

Did this answer your question?