Title: Smart Media Replacement Author: Troy Chaplin Published: November 17, 2025 Last modified: November 17, 2025 --- Search plugins ![](https://ps.w.org/smart-media-replacement/assets/banner-772x250.png?rev=3397667) ![](https://ps.w.org/smart-media-replacement/assets/icon-256x256.png?rev=3397667) # Smart Media Replacement By [Troy Chaplin](https://profiles.wordpress.org/areziaal/) [Download](https://downloads.wordpress.org/plugin/smart-media-replacement.1.0.0.zip) * [Details](https://sa.wordpress.org/plugins/smart-media-replacement/#description) * [Reviews](https://sa.wordpress.org/plugins/smart-media-replacement/#reviews) * [Installation](https://sa.wordpress.org/plugins/smart-media-replacement/#installation) * [Development](https://sa.wordpress.org/plugins/smart-media-replacement/#developers) [Support](https://wordpress.org/support/plugin/smart-media-replacement/) ## Description Smart Media Replacement is a WordPress plugin that allows you to replace media files while maintaining their original URLs and metadata. This is particularly useful for updating files like PDFs, images, or other documents without breaking existing links, especially when organizing media in year and month based folders. #### Features * Replace media files while maintaining original URLs * Preserves all existing links (both internal and external) * Maintains file metadata and relationships * Simple and intuitive interface in the WordPress Media Library * Supports all file types supported by WordPress * Validates file names to prevent accidental URL changes * Enforces dimension matching for images to prevent layout issues * Automatically handles WordPress scaled images * Validates file type matching to ensure consistency * AJAX-based replacement with error handling #### Important Requirements **Filename Matching** The new file MUST have exactly the same filename as the original file. For example, if your original file is `logo.png`, your replacement must also be named `logo.png`. **Image Dimensions (Images Only)** For images, the replacement MUST have identical dimensions (width × height) to prevent layout issues. **File Types** The replacement file must be the same file type as the original. The plugin validates MIME types to ensure consistency. #### Privacy This plugin: * Does not collect or transmit any user data * Does not use cookies* Only processes files locally on your server * Does not communicate with external services ### Usage 1. Go to the WordPress Media Library 2. Find the file you want to replace 3. Click on the file to view its details 4. Look for the “Replace File” button in the attachment details 5. Click “Replace File” and select your new file 6. The replacement will happen automatically ## Screenshots * [[ * Replace File button in the Media Library attachment details * [[ * Repalce file from the list of media library items ## Installation 1. Download the plugin files 2. Upload the `replace-media` folder to the `/wp-content/plugins/` directory, or install the plugin through the WordPress plugins screen directly 3. Activate the plugin through the ‘Plugins’ screen in WordPress ## FAQ ### Why do I get an error about file names not matching? The replacement file must have exactly the same filename as the original file. Rename your replacement file to match the original filename exactly, including the file extension. ### Why must image dimensions match? Enforcing identical dimensions prevents layout issues where images might break your design. If you need to change dimensions, consider uploading as a new image instead. ### What if my image was scaled by WordPress? If WordPress automatically scaled your original image (large uploads), upload your replacement with the original filename (without `-scaled`). The plugin will handle the scaling automatically and show you the correct filename if there’s a mismatch. ### Can I replace a JPG with a PNG? No, the replacement file must be the same file type as the original to maintain consistency and prevent unexpected behavior. ### The button is not appearing, what should I do? Make sure you’re viewing the attachment details (click on a media item), clear your browser cache, and check that you have permission to edit media files. ### Do I need special permissions? Yes, you must have the `edit_post` capability for the specific attachment. Contact your site administrator if you believe you should have access. ### Can I disable dimension enforcement for specific images? Yes, developers can use the `smart_media_replacement_enforce_dimensions` filter to disable or customize dimension enforcement for specific attachments. See the Developer Hooks section for details. ## Reviews There are no reviews for this plugin. ## Contributors & Developers “Smart Media Replacement” is open source software. The following people have contributed to this plugin. Contributors * [ Troy Chaplin ](https://profiles.wordpress.org/areziaal/) [Translate “Smart Media Replacement” into your language.](https://translate.wordpress.org/projects/wp-plugins/smart-media-replacement) ### Interested in development? [Browse the code](https://plugins.trac.wordpress.org/browser/smart-media-replacement/), check out the [SVN repository](https://plugins.svn.wordpress.org/smart-media-replacement/), or subscribe to the [development log](https://plugins.trac.wordpress.org/log/smart-media-replacement/) by [RSS](https://plugins.trac.wordpress.org/log/smart-media-replacement/?limit=100&mode=stop_on_copy&format=rss). ## Changelog #### 1.0.0 * Initial release * Replace media files while maintaining URLs * Filename validation to prevent URL changes * Image dimension enforcement to prevent layout issues * WordPress scaled image handling * File type validation for consistency * AJAX-based replacement with error handling * Developer hooks for customization ## Meta * Version **1.0.0** * Last updated **5 months ago** * Active installations **Fewer than 10** * WordPress version ** 6.6 or higher ** * Tested up to **6.9.4** * PHP version ** 7.0 or higher ** * Language * [English (US)](https://wordpress.org/plugins/smart-media-replacement/) * Tags * [attachment](https://sa.wordpress.org/plugins/tags/attachment/)[media](https://sa.wordpress.org/plugins/tags/media/) [pdf](https://sa.wordpress.org/plugins/tags/pdf/)[replace](https://sa.wordpress.org/plugins/tags/replace/) [upload](https://sa.wordpress.org/plugins/tags/upload/) * [Advanced View](https://sa.wordpress.org/plugins/smart-media-replacement/advanced/) ## Ratings No reviews have been submitted yet. [Your review](https://wordpress.org/support/plugin/smart-media-replacement/reviews/#new-post) [See all reviews](https://wordpress.org/support/plugin/smart-media-replacement/reviews/) ## Contributors * [ Troy Chaplin ](https://profiles.wordpress.org/areziaal/) ## Support Got something to say? Need help? [View support forum](https://wordpress.org/support/plugin/smart-media-replacement/)