Renaming an image used to be the kind of operation you’d avoid — change the filename on disk and you’d break every post, page-builder block and external bookmark that points at it. The plugin’s filename flow turns it into a single click: the rename happens on disk, every reference inside your content is rewritten to point at the new URL, and a 301 redirect catches anything left over so search engines and external links keep working.
What happens when you save a new filename
After you click Save Changes in the Filename modal, six things happen in order:
The file is renamed on disk
The image file in wp-content/uploads/ is renamed via WordPress’s filesystem layer. The attachment record is updated to point at the new path, including all size variants (e.g. -300x200, -scaled, etc.).
Page-builder content is rewritten
The plugin scans your posts and pages for any reference to the old URL and rewrites it to the new one. Six adapters ship with the plugin: Gutenberg, Elementor, WPBakery, Visual Composer, Uncode and Divi. The Gutenberg adapter always runs; the other five register only when that builder is detected on the site, so an inactive builder costs you nothing.
Multiple URL variants are caught
The rewrite handles plain URLs, URL-encoded variants, escaped variants, and all WordPress image sizes. So old-name-300x200.jpg, old-name-scaled.jpg and the URL-encoded form all get rewritten — not just the canonical URL.
A 301 redirect is registered (if enabled)
An entry is written to the redirects table so the old URL serves a 301 to the new one. Search engines pick up the move automatically; bookmarks, external embeds and any hard-coded references keep working. This step is optional — controlled by a setting (see below).
The change is logged
An entry is added to the Change History with the old filename, the new one, and the count of posts/pages updated.
Caches are cleared
The image’s row in the table refreshes, the SEO score recalculates, and any cached score is invalidated so the next dashboard view reflects the new state.
Supported page builders
Builders the rename flow updates
| Feature | What it updates |
|---|---|
| Gutenberg (block editor) WordPress core’s default editor. | Image blocks, gallery blocks, cover blocks, and any other block whose JSON references the image URL. |
| Elementor The popular drag-and-drop builder. | Elementor stores layout in post-meta. The adapter walks the saved data and rewrites image URLs inline. |
| WPBakery Block-based shortcodes. | WPBakery shortcode parameters that reference images get rewritten. |
| Visual Composer Separate from WPBakery despite shared origin. | VC’s distinct data shape is handled by its own adapter — both modern Visual Composer and legacy WPBakery sites are covered. |
| Uncode Theme-bundled builder. | Uncode’s builder-specific meta and shortcodes are scanned and rewritten. |
| Divi Elegant Themes builder — adapter added in plugin 1.0.4. |
et_pb_* shortcodes that carry image URLs, page-level custom CSS in the _et_pb_custom_css meta, and Divi Library plus Theme Builder templates (post types et_pb_layout, et_template and the header, body and footer layout types). After the rewrite the adapter clears Divi’s static CSS cache — transients, the page-resource cache bust, and the uploads/et-cache directory — so regenerated stylesheets point at the new URL. Layouts that don’t store image URLs as shortcode or CSS strings stay untouched.
|
Drafts, scheduled posts and custom post types
The rename flow doesn’t skip drafts or scheduled posts — they’re updated too, so when they go live the URLs are already correct. Custom post types are also covered, provided they appear in your Optimization Settings as a tracked post type.
Turning redirect capture on or off
By default, every filename change registers a 301 redirect from the old URL to the new one. That’s almost always what you want — it protects against any reference that lives outside your WordPress install (external links, bookmarks, indexed pages, page-builder content you forgot about).
Some server setups answer old URLs before WordPress can
The 301 redirect is served by WordPress, which only sees a request for an old image URL when your web server passes requests for missing files through to it. Standard Apache and nginx WordPress configurations do this. Some setups do not — nginx static-asset rules that return 404 directly, hardened hosting panels, or a CDN answering from its edge. On those servers the redirect never runs and external links to old URLs get an error instead. The plugin tests this for you: the Redirects screen shows a delivery check with a Test redirects now button, the result appears in Site Health, and a warning appears on plugin screens whenever a test shows redirects are not reaching visitors.
If you have a reason to disable redirect capture (for example, in development environments where you don’t want to clutter the redirects table), turn off Enable Redirects in the 301 Redirects card on the Settings page. The same card holds Auto-expire After — 6, 12 or 24 months, or Never — which marks redirects older than that as expired. With capture off, rename still works — the file is renamed and content is updated — but no 301 entry is created, and the old URL 404s. The Redirects Manager lists what capture has already recorded.
What the rename flow doesn’t touch
Out of scope (use the 301 redirect to catch these)
| Feature | Why it isn't auto-updated |
|---|---|
| Hand-written theme code PHP files in your theme folder. |
Hard-coded image URLs in header.php, functions.php, custom templates, etc. aren’t scanned. Update them manually, or rely on the 301 to keep them working until you do.
|
| CDN / server-side caches Cached versions on a CDN, full-page cache, or object cache. | The plugin can’t reach into your CDN or your hosting cache. Purge those after a bulk rename if it matters. |
| External integrations Newsletters, social-media embeds, third-party platforms. | Anything outside your WP install. The 301 redirect catches them on the next fetch; they don’t need manual updates. |
Use the Image Usage modal before you rename
If you want to know exactly where an image is referenced inside your site before you rename it, open the Image Usage modal from the Usage column. It lists every post, page and page-builder reference, classified by type.
Further reading
This page covers the mechanics inside the plugin. For the wider picture — what a rename does to a live media library, which references move on their own, and how to name new uploads so the rename never becomes necessary — there is a full walkthrough on the blog.
SEO image naming: how to rename WordPress files safely
What a rename moves, which references get rewritten, which need a 301, and when to leave the name alone.