Ever updated a PDF and realized half your site links to the old version? Or replaced a hero image and watched your carefully-tuned page layout collapse? Smart Media Replacement solves both problems \u2014 and adds a safety net you'll wish you had earlier.<\/p>\n\n
Replace the file, keep the URL.<\/strong> When you swap an attachment with this plugin, the file's URL never changes. Every existing link, every email that points to it, every page that embeds it, every SEO ranking \u2014 all of it keeps working. No 404s, no broken references, no scrambling to update old content.<\/p>\n\n Full revision history, one-click restore.<\/strong> Every replacement automatically snapshots the previous version. Made a mistake? Roll back instantly. Want to see what the file looked like three months ago? Download it. Each revision is timestamped, attributed to the user who made it, and can carry an optional note describing what changed.<\/p>\n\n Works where you work.<\/strong> Replace from the Media Library, or from inside any block's Replace toolbar in the block editor \u2014 image, cover, video, audio, file, gallery, and more. The editor refreshes in place, no page reload, no lost work.<\/p>\n\n Safe by default.<\/strong> The plugin validates filenames, file types, and image dimensions to keep your URLs intact and your layouts unbroken. WordPress's auto-scaled images are handled transparently. Revisions land in a database table that's self-healing on every admin load, and the plugin's settings page gives you control over how many revisions to keep, how long to retain them, and which file types are tracked.<\/p>\n\n Replacement and URL preservation<\/strong><\/p>\n\n Revision history<\/strong><\/p>\n\n Block editor integration<\/strong><\/p>\n\n Validation safeguards<\/strong><\/p>\n\n Built-in admin<\/strong><\/p>\n\n Multisite-ready<\/strong><\/p>\n\n WP-CLI<\/strong><\/p>\n\n Other<\/strong><\/p>\n\n This plugin is fully self-contained and respects your privacy:<\/p>\n\n On WordPress multisite the plugin is network-activate only \u2014 activate it once from Network Admin \u2192 Plugins, then configure it at Network Admin \u2192 Settings \u2192 Media Replacement. The settings you choose apply to every site on the network. There is no per-site settings page on multisite.<\/p>\n\n\n Yes \u2014 that's the whole point. The replacement keeps the file's URL and ID unchanged, so every existing link, embed, share, and SEO reference continues to work normally.<\/p><\/dd>\n Yes. As long as revisions are enabled for the file type, every replacement preserves the previous version. Open the file's revision history and click Restore<\/strong> on any past version. The current file is also snapshotted before the restore, so nothing is lost.<\/p><\/dd>\n Yes. Every block that has a Replace toolbar \u2014 image, cover, video, audio, file, gallery, media-text, post-featured-image \u2014 gets an Update existing file<\/strong> option in the Replace dropdown. The editor refreshes in place after replacement, so you don't lose unsaved work.<\/p><\/dd>\n WordPress regenerates all configured image sizes (thumbnail, medium, large, etc.) automatically. Their URLs stay stable too, so responsive images and srcset attributes continue working.<\/p><\/dd>\n Yes. Each revision has its own Download button. You can also download a ZIP archive containing every revision for a file at once.<\/p><\/dd>\n That's how WordPress serves files \u2014 the URL contains the filename. Matching the original filename is what keeps your existing links intact. The plugin shows you the exact filename to use if there's a mismatch.<\/p><\/dd>\n Different dimensions can break responsive layouts, hero image sizing, and carefully-tuned cropping across your site. Enforcing identical dimensions protects against unexpected layout shifts. Developers can disable this per-attachment with the No. The replacement file must be the same MIME type as the original. Mixing file types can break image processing, browser display, and SEO. If you need to change formats, upload as a new image.<\/p><\/dd>\n If WordPress automatically created a Revisions are created on replacement<\/strong>, not on the original upload \u2014 so a brand-new attachment shows no history until you've replaced it at least once. Also check Media \u2192 Replacement Settings: the \"Enable Revisions For\" option lets you scope revisions to documents only, images only, or all file types. If your attachment's type isn't covered, no revisions will be tracked.<\/p><\/dd>\n Yes. The plugin ships with Yes \u2014 you need the Multisite behavior is now consistent and centrally managed.<\/p>\n\n Upgrading on multisite:<\/strong> per-site settings stored under v1.1.x are not carried forward to the network store. After upgrading, a super admin should visit Network Admin \u2192 Settings \u2192 Media Replacement once and confirm the values. Single-site installs are unaffected.<\/p>\n\n A major feature release. Revision history, block editor integration, and a handful of reliability improvements for managed hosts.<\/p>\n\n New features<\/strong><\/p>\n\n Reliability improvements<\/strong><\/p>\n\n Security hardening<\/strong><\/p>\n\nUse cases<\/h4>\n\n
\n
Features<\/h4>\n\n
\n
-scaled<\/code> large images<\/li>\n<\/ul>\n\n\n
\n
\n
\n
\n
\n
wp smr db check<\/code> \u2014 verify the revisions table exists (non-zero exit code if missing, safe for CI pipelines)<\/li>\nwp smr db repair<\/code> \u2014 recreate the table if missing; idempotent, safe to run when the table already exists<\/li>\nwp smr db status<\/code> \u2014 revision counts and storage usage; --network<\/code> for a per-site breakdown on multisite<\/li>\nwp smr db cleanup<\/code> \u2014 delete expired revisions immediately, with --dry-run<\/code> to preview and --network<\/code> for all sites<\/li>\n<\/ul>\n\n\n
wp smr db repair<\/code> for on-demand recovery<\/li>\nPrivacy<\/h4>\n\n
\n
Usage<\/h3>\n\n
From the Media Library<\/h4>\n\n
\n
From the block editor<\/h4>\n\n
\n
Viewing and managing revisions<\/h4>\n\n
\n
\n
smart-media-replacement<\/code> folder to \/wp-content\/plugins\/<\/code><\/li>\nMultisite<\/h4>\n\n
\n
Will my existing links still work after I replace a file?<\/h3><\/dt>\n
Can I undo a replacement if something goes wrong?<\/h3><\/dt>\n
Does this work in the block editor?<\/h3><\/dt>\n
What happens to image thumbnail variants after replacement?<\/h3><\/dt>\n
Can I download a previous version of a file?<\/h3><\/dt>\n
Why must my replacement file have the same name as the original?<\/h3><\/dt>\n
Why must image dimensions match?<\/h3><\/dt>\n
smart_media_replacement_enforce_dimensions<\/code> filter if needed.<\/p><\/dd>\nCan I replace a JPG with a PNG?<\/h3><\/dt>\n
What if my image was scaled by WordPress?<\/h3><\/dt>\n
-scaled<\/code> variant (typical for uploads over 2560px), upload your replacement with the original<\/strong> filename \u2014 without the -scaled<\/code> suffix. The plugin handles the scaling and regenerates all variants automatically. If you upload with the wrong filename, the error message will tell you exactly what name to use.<\/p><\/dd>\nI have revisions enabled but I don't see any history. Why?<\/h3><\/dt>\n
Is there a WP-CLI interface?<\/h3><\/dt>\n
wp smr db check<\/code>, wp smr db repair<\/code>, wp smr db status<\/code>, and wp smr db cleanup<\/code>. These are useful in deployment pipelines, after database restores, and on large multisite networks where you want to run retention cleanup on a real system cron instead of relying on WP-Cron. All commands support --network<\/code> and --site-id=<id><\/code> on multisite; wp smr db cleanup<\/code> also accepts --dry-run<\/code> and --yes<\/code>.<\/p><\/dd>\nDo I need special permissions?<\/h3><\/dt>\n
edit_post<\/code> capability for the specific attachment. This matches WordPress's standard media editing permission model.<\/p><\/dd>\n\n<\/dl>\n\n\nWhat's new in 1.2.0<\/h4>\n\n
\n
What's new in 1.1.1<\/h4>\n\n
\n
\n