Replace a media file

Replace file swaps the file behind an existing attachment and keeps the attachment record. The ID, title, alt text, caption, description, Plathix folder and attached post stay the same. Pages that use the attachment by its ID show the new file without any editing.

When you need this

• A new logo for a client site. An agency gets a new logo and replaces logo.png in Brand › Logos. Pages and widgets that use the logo by attachment ID show the new one.
• A corrected product photo. A WooCommerce store updates a product photo. The product keeps the same image attachment, so nobody has to set the image again.
• An updated infographic. A blog replaces a chart in Infographics after the numbers change. The title, alt text and caption stay as the editor wrote them.

How to replace a file

You can start a replacement from three places:

• Grid view: the Replace file field in Attachment details. The same field appears in the media window that editors open, for example from the block editor.
• List view: the Replace file link under the file name.
• Attachment edit page: the Replace file button in the Folder & file box on the right.

The field in Attachment details and the Folder & file box show the help text “Keeps the same attachment ID and WordPress relationships. Direct URL references may require manual review if filename or file type changes.” The steps below use grid view.

1. Go to Media → Library and switch to grid view.
2. Click the file you want to replace. Attachment details opens.
3. Under Replace file, click the Replace file button.
   

4. In the file dialog, pick the new file. The replacement starts at once. There is no confirmation step and no preview.
5. Wait while the button reads “Replacing…”. In grid view, a spinner also covers the preview.
6. Wait for the notice “File replaced successfully.” The file name, type, size and dimensions in the panel update in place.

Other messages you can see:

• “File replaced, but the preview could not be refreshed. Reload the page to see the new file.” The file is replaced. Only the preview is old. In the media window that editors open, which has no large preview, this notice can also appear after a successful replacement.
• “The file may have been replaced, but the server response could not be confirmed. Reload the page to check.”
• “File replaced, but some cleanup steps need manual review.” The notice lists what needs attention, for example “Missing thumbnail sizes after replace: medium, large”.

How to check what changed after the replacement

1. Open the file in Attachment details again.
2. Compare File name, File type, File size and Dimensions with the old values.
3. Compare File URL with the old address. If it changed, update the pages that use the old address.

What stays the same:

• The attachment ID.
• Title, alt text, caption and description.
• The Plathix folder and its file count.
• The post the file is attached to.
• The file name. If you replace logo.png with logo-final-v3.png, the file is still called logo.png. The name of the uploaded file is ignored.
• The URL, but only when the new file has the same extension and lands in the same upload folder.

What changes:

• The file on disk. After a successful replacement, the old file and its old thumbnails are deleted.
• The MIME type, if the new file has a different type.
• Width, height and other technical metadata.
• Thumbnails. For raster images, such as JPG, PNG, GIF and WebP, WordPress creates all registered sizes again. SVG files have no thumbnails. If the new file is not an image, the old image sizes are removed.
• The extension, if the type changes. For example, logo.png becomes logo.jpg, and the old address stops working.
• The upload folder. With month folders on (the WordPress default), the new file is written to the current month’s folder. A file uploaded in an earlier month therefore gets a new URL even with the same type, and the old address stops working.

If another file in that folder already has the new name, Plathix writes over it, and the original of that other file is lost. Read the first item under Limits before you change a file’s type or replace an older file.

How to make visitors see the new file

Plathix saves the time of each replacement on the attachment. It adds that time as a version parameter to the file addresses it outputs, so browsers fetch the new file. On the screen where you replaced the file, the parameter is ?v=. On the site it is ?plx_v=. Plathix adds it to the main file URL and to image addresses, including responsive image sizes.

An address written directly into post HTML gets no parameter. Browsers, the block editor and CDNs can keep showing the old file until their cache expires. Block editor images with responsive sizes show the new file to returning visitors. A Thumbnail-size image without responsive sizes, the block editor itself and Elementor Image widgets can show the old copy until the browser cache expires.

1. Open a page that shows the file.
2. If the old file still shows, clear the cache of your caching plugin or CDN, if the site has one.
3. Reload the page and bypass the browser cache, for example with Ctrl+Shift+R.
4. If the file URL changed, open the post in the editor and pick the file again from the Media Library. Plathix does not rewrite URLs inside post content.

Example

Suppose your blog uses the Blog & Content tree, and the folder Editorial › Featured Images holds summer-campaign.png. It was uploaded this month and is the featured image of a blog post. The designer sends a corrected file, summer-campaign-final.png.

1. Open Media → Library and click Featured Images under Editorial in the folder tree.
2. Click summer-campaign.png, then click Replace file.
3. Pick summer-campaign-final.png.

Result: you would see the notice “File replaced successfully.” The file would still be called summer-campaign.png, with the same ID, title and alt text, in the same folder. The URL would stay the same, because the type and the month folder did not change. The post would show the new picture as its featured image, because WordPress stores the featured image by attachment ID.

If the designer had sent summer-campaign.jpg instead, the file would become summer-campaign.jpg. Pages that embed the old .png address would then need an update.

What we tested

Limits

• Check the file name first. The new file takes the old file’s name with the new extension and goes to the folder WordPress uses for new uploads. If another file in that folder already has that name, Plathix writes over it, and the original of that other file is lost. This can happen in two cases:
  • You change the type, for example logo.png to a JPG, and another file named logo.jpg is already in that folder.
  • The original sits in an earlier month folder, and the current month folder already holds another file named logo.png.
  • Before such a replacement, search the Media Library for the new file name and check the results.
• Month folders. Replacing a file from an earlier month moves it to the current month folder and changes its URL. Update the pages that use the old address.
• No undo and no version history. The old file is deleted.
• No bulk replace, no replace by URL from the admin screens and no search-and-replace of URLs in post content.
• One replacement at a time per attachment. A parallel attempt gets “A replace operation is already in progress for this attachment.”
• If you replace many files in a short time, you get “Too many requests.” Wait a little and try again.
• Replace file needs a MySQL or MariaDB database.
• File types. The file type is checked against the types WordPress allows on the site. A file that fails gets “Uploaded file type is not allowed.” You can change the type, for example PNG to JPG or image to PDF. Keep the same type where you can, because otherwise the URL changes.
• File size. The upload limits in your server’s PHP settings apply.
• SVG. The result depends on the policy in Plathix → Settings → SVG:
  • Allow SVG uploads with sanitisation (recommended): your role must be in SVG Allowed Roles, otherwise you get “Your role is not allowed to upload SVG files.” The file can be at most 2 MB, otherwise you get “SVG file exceeds the maximum allowed size.” The markup is cleaned before it is saved, and strict safe mode applies.
  • Block SVG uploads site-wide (including SVG allowed by other plugins): an SVG cannot be used as a replacement. You get “Uploaded file type is not allowed.”
  • Do not manage SVG (leave it to other plugins; Plathix will not sanitise): Replace accepts an SVG only if another plugin allows SVG. Plathix then still cleans it and applies its own role list, the 2 MB limit and strict safe mode. The SVG tab hides the role list under this policy.
  • A compressed .svgz file is refused with “Uploaded file type is not allowed.” Under Do not manage SVG, if another plugin allows SVGZ, the message is “Compressed SVGZ files are not supported.” instead.
• A file in Trash cannot be replaced. You get “Attachment was moved to trash.”
• Who can replace. You need WordPress permission to edit that file and the Plathix access level Full or Upload. In Free, users who can manage site options, such as administrators, get Full, and users who can upload files, such as editors and authors, get Upload. An author can therefore replace only their own files, while editors and administrators can replace any file. An author who tries to replace another user’s file gets “Actor is not allowed to replace this attachment.”
• PRO. With PRO active and licensed, you also get the WP-CLI command wp plathix media replace --id=<id> --file=<path> and a “File replaced” entry in the Audit Log. With PRO role permissions, roles set to View or None cannot replace. See PRO. Use the PRO version released for your Plathix version.
• Large images. WordPress itself may store an image wider or taller than 2560 px as a -scaled copy, which changes the file name.

In short

Replace file swaps only the file and keeps the attachment ID, its text fields, its Plathix folder and its attached post. The file keeps its old name, and only the extension follows the new file. The URL also changes when the original sits in an earlier month folder. A file with the same name in the target folder is overwritten and its original is lost, so check the name first. Plathix adds a version parameter so most requests get the new file, but cached pages and addresses inside post HTML may need a manual refresh. There is no undo.