Swap a file's content without breaking a single link
Media Replace overwrites the file behind an attachment in place — same attachment ID, same URL, regenerated thumbnails — so every post, gallery and link that already references it just keeps working.
- A Replace File button on every attachment, in the library and on its edit screen.
- The URL and attachment ID never change.
- Every image size regenerates automatically.
- A warning appears if the replacement is a different file type.
What does Media Replace do?
Once the media_replace module is active, TOWP_Media_Replace adds a "Replace File" button to the media library and to each attachment's edit screen. Consequently, uploading a replacement overwrites the original file in place, deletes the old thumbnails, regenerates every registered image size against the new file, and updates the attachment's metadata, all under the exact same attachment ID and URL. Because browsers and caches would otherwise keep serving the old file from that same address, the module also stamps a version parameter across every place WordPress can render that URL, including directly into post_content in the database, so the new file actually shows up everywhere.
Swapping a file shouldn't mean starting over
Since a fresh upload always creates a new identity, correcting one file usually means chasing down every place the old one was used.
Deleting an attachment and uploading its replacement
As a result, WordPress assigns a brand new attachment ID and address, leaving every post, gallery and page that referenced the original pointing at nothing.
Even an in-place swap fights the browser's own cache
However, overwriting a file at the same URL only solves the broken-link problem; browsers and CDNs that already cached the old file at that exact address won't necessarily notice anything changed.
Same attachment, a different file behind it
Instead, this module replaces the file itself while keeping the attachment record, its ID and its URL completely untouched.
Same ID, same URL, a completely new file
Because nothing about its identity or address changes, nothing that already references the attachment needs to change either.
Every thumbnail regenerated automatically
Similarly, all registered image sizes get rebuilt against the new file, the same way they would for a fresh upload.
A warning before a type mismatch surprises anyone
If the replacement file is a different type than the original, a warning also appears before the swap goes through.
Seven layers of cache-busting, one clean replacement
Accordingly, every capability below is present in the supplied PHP class, its JS asset and the settings registration.
An exact copy of the original file path
First, uploading a replacement moves it to the precise location of the original file, so the attachment's URL never changes.
Every image size rebuilt
Next, wp_generate_attachment_metadata() runs against the new file and regenerates every registered thumbnail size exactly as it would on first upload.
Old thumbnail references get updated too
Then, if a different aspect ratio changes a thumbnail's filename, the module updates every place that filename was referenced to the new one.
Seven separate rendering paths covered
Consequently, a version parameter gets appended to the attachment URL, content, JS/Gutenberg data, image_src calls, the REST API response and every srcset entry.
Not just a runtime filter
Furthermore, that same version parameter gets written straight into post_content for every post referencing the file, since page caches and stored Gutenberg markup can otherwise bypass a PHP-only filter.
Alt text and caption cleared
Finally, since alt text, description and caption belonged to the original file's content, the module clears them rather than carrying them over to a file they no longer describe.
Where an in-place swap helps most
Overall, this module supports any situation where a file needs correcting without touching what already references it.
Fixing a low-quality or incorrect upload
Because the URL never changes, swapping in a corrected version of a file doesn't require touching any of the posts, pages or galleries that already reference it.
Updating a document or a logo everywhere it's used
Similarly, replacing a PDF, a logo or a diagram in one place makes every embed across the site show the new version automatically.
Correcting a file uploaded with the wrong content entirely
Even so, a genuinely wrong file, of a different type even, can get fixed while keeping the original attachment's ID and any links already pointing at it.
A file corrected, nothing else disturbed
Together, these combine a genuinely non-destructive fix with the cache-busting that makes it actually visible.
Regenerated once, at the moment it matters
In fact, its heaviest work happens exactly once, during the replacement itself.
Regeneration happens once, at replacement time
Specifically, thumbnails rebuild during the replace action itself, not on subsequent page loads.
A targeted database update, not a full scan
Likewise, only posts referencing the replaced file's path get searched by the content-stamping step, not every post on the site.
Assets load only where the button appears
Additionally, enqueueing happens only on the media library and post editor screens, where the Replace File button can actually appear.
Checked at every step, nothing skipped
Before any code touches anything on disk, permission, nonce and file type all get verified.
Capability checks before any file is touched
Specifically, both upload_files and edit_post on the specific attachment are required before a replacement can proceed.
Nonce verification on the AJAX request
Likewise, before processing, the replace action checks a nonce, the same protection WordPress uses throughout its own admin.
File type still validated
In addition, wp_check_filetype() still confirms the replacement is a permitted file type, rejecting a disallowed type regardless of what the original file was.
A visible warning for type mismatches
Even then, replacing a file with a different type still succeeds, but the visible warning means it never happens by surprise.
Built on the same native functions a fresh upload uses
Indeed, WordPress core provides the APIs this code integrates through, so this page makes no compatibility claim beyond the verified implementation.
wp_handle_upload()
Specifically, this is the same core function WordPress uses for every standard file upload, handling the raw incoming file before it moves into place.
wp_generate_attachment_metadata()
Similarly, this is the exact function WordPress runs on a fresh upload to build every registered image size, applied here to the replacement file.
Seven native filters and functions
Together, wp_get_attachment_url, the_content, wp_prepare_attachment_for_js, wp_get_attachment_image_src, rest_prepare_attachment and wp_calculate_image_srcset cover a distinct way WordPress renders the URL.
TheOneWP versus common alternatives
Below, compare the verified Media Replace implementation with deleting and re-uploading a file manually.
| Capability | TheOneWP Media Replace | Other common solutions |
|---|---|---|
| Keeping the same URL and ID | Guaranteed by an in-place file overwrite | Deleting and re-uploading always creates a new ID and address |
| Regenerating thumbnails | Every registered size rebuilt automatically | Often requires a separate manual regenerate step |
| Cache-busting coverage | Seven distinct rendering paths, plus a direct DB stamp | Frequently limited to just the main URL, missing srcset and cached content |
| Aspect ratio changes | Old thumbnail filenames found and updated site-wide | Can leave broken thumbnail references after a ratio change |
| Administration | One button per attachment, nothing else to configure | Usually requires a dedicated plugin for equivalent reliability |
Replace a file in four steps
Afterward, check the result on a page that actually embeds the file before considering it done.
Enable Media Replace
First, activate the module from the TheOneWP Content settings tab.
Open Replace File on the attachment
Then, use the row action in the media library, or the button on the attachment's own edit screen.
Drag in or select the replacement
Next, drop the new file into the dialog, or click to choose it, and confirm any type-mismatch warning that appears.
Confirm the replacement everywhere it's used
Finally, check a post or page that embeds the file to confirm the new version displays correctly.
Confirm the result, not just the upload
Although doing the replacement itself is quick, verifying it landed everywhere is what actually makes it reliable.
Keep the same file type where possible
Since matching the original type avoids the warning entirely, it also keeps behavior most predictable.
Replace rather than delete and re-upload
Whenever a file just needs correcting, replacing it therefore preserves every existing reference automatically.
Check a cached or CDN-fronted page after replacing
If the site sits behind a page cache or CDN, it's also worth verifying the new file actually appears there too, since some external caching layers sit outside what this module can reach.
Confirm thumbnails after a significant aspect ratio change
Because a large change in aspect ratio is exactly the case where thumbnail filenames change, it's worth a quick visual check.
Avoid overlooking what the warning is telling you
Nonetheless, a couple of details are easy to skip past when a replacement finishes quickly.
Ignoring the type-mismatch warning
Indeed, swapping in a different file type changes the content while the URL stays the same, which is exactly why the warning exists; read it before confirming.
Forgetting an external cache or CDN sits in front of the site
Although this module's cache-busting covers everything WordPress itself renders, a separate CDN layer may still need its own cache purge.
Expecting alt text and captions to carry over
Since they described the original file's content rather than the replacement's, alt text, description and caption get cleared on purpose.
Media Replace FAQ
Overall, these answers come directly from the verified class, its JS asset and the settings registration.
What does Media Replace do?
Essentially, it overwrites the file behind an existing attachment, regenerating thumbnails and updating metadata, while keeping the same attachment ID and URL.
Does replacing a file break links or embeds pointing at it?
No. Since the URL and attachment ID never change, every post, gallery and direct link that already references the file keeps working.
What happens to the old thumbnails?
Old thumbnails get deleted and then regenerated fresh from the new file, matching every image size currently registered on the site.
Can I replace a file with a different file type?
Yes, though a warning appears first, since the URL stays the same while the actual content changes.
Will visitors see the old cached version after a replacement?
Specifically to prevent that, a version parameter gets stamped across every way WordPress renders the URL, including directly into stored post content.
What happens to alt text and captions after a replacement?
They get cleared, since they described the original file's content rather than whatever replaces it.
Does this affect a CDN or external caching layer in front of the site?
Although the cache-busting covers everything WordPress itself renders, a separate CDN may still need its own cache purge.
What happens if the new file has a different aspect ratio?
In that case, the module finds and updates any thumbnail filenames that change as a result, everywhere they were referenced.
Who can replace a file?
Only a user with upload permission and edit access to that specific attachment.
Is there anything to configure beyond enabling the module?
No. The Replace File button appears automatically on every attachment once the module is on.
Stop deleting and re-uploading to fix one file.Replace it, and let every link keep working.
Overall, use Media Replace to swap a file in place, with thumbnails regenerated and every reference across the site staying intact.