Duplicate Media Guard

By Rashed Uzzaman

★ 5.0/5 (3 ratings)40+ active installationsVersion 2.1.1

Replace existing media files in WordPress without changing their URL or attachment ID. Prevent duplicate media uploads with smart filename and image h …

Description

Duplicate Media Guard is the easiest way to replace existing media files in WordPress and prevent duplicate uploads — all without breaking your URLs or losing your attachment IDs.

Need to replace a media file in your WordPress Media Library? This plugin adds a Replace Media button directly in the Media Library. Simply pick a file, upload the replacement, and choose whether to keep the existing filename and URL or update all links automatically. The attachment ID is always retained, so nothing breaks.

Beyond media replace, Duplicate Media Guard keeps your Media Library clean by detecting duplicate uploads before they happen. Filename checks catch common re-uploads, exact file hashing identifies byte-identical images, and perceptual hashing can spot resized or recompressed copies even when the filename is different.

Why use this plugin?

  • Replace media in WordPress without creating a new attachment or breaking existing links.
  • Stop wasting storage on accidental duplicate uploads.
  • Keep your Media Library organized with smart duplicate detection.
  • Works with the standard WordPress Media Uploader — no custom UI to learn.

How Replace Media works:

Enable Enable Media Replace in the plugin settings. A Replace media link then appears in the Media Library for any file you have permission to edit. Upload the new file and choose one of two replace modes:

  • Replace file only — keeps the same filename, URL, and folder. The replacement must be the same file type.
  • Replace file and update all links — uses the new filename and automatically updates all matching references stored in WordPress content and metadata.

The attachment ID is preserved in both modes.

Duplicate detection examples:

  • logo.png and logo.png → Duplicate
  • logo.png and logo.jpg → Duplicate (when extension check is disabled)
  • banner.webp and banner.webp → Duplicate
  • photo.jpg and a resized or recompressed copy.webp → Possible visual duplicate (when visually similar detection is enabled)

This helps reduce unnecessary duplicates and storage use while still allowing intentional uploads.

Key Features

  • Replace existing media file while retaining its attachment ID and URL — enable with one setting.
  • Review possible image duplicates with existing-media previews before uploading.
  • Detect byte-identical images using exact file hashes.
  • Identify resized or recompressed images using perceptual hashes.
  • Match filenames with or without their file extensions.
  • Enable or disable duplicate protection and image hash checks independently in the settings.
  • Use the standard WordPress Media Uploader — no custom upload interface needed.
  • Index existing image fingerprints gradually in the background.

How to Replace Media in WordPress (Step by Step)

  1. Go to Settings → Duplicate Media Guard and turn on Enable Media Replace.
  2. Open your WordPress Media Library.
  3. Click any media item and select Replace media.
  4. Upload the replacement file.
  5. Choose your replace mode and click Replace — the attachment ID and all internal links are preserved.

Duplicate Detection

  1. Select an image through the WordPress Media Library.
  2. The plugin checks the filename, exact file hash, and perceptual hash of indexed images.
  3. If potential matches are found, a warning shows previews and lets you cancel or proceed. Files with no matches upload without a confirmation.
  4. Files uploaded outside the standard Media Uploader retain the server-side filename duplicate check.

Use Enable Duplicate Protection to turn duplicate checks on or off. Use Enable Image Hash Checks to control exact and visual image matching. When image hash checks are disabled, filename duplicates use the standard WordPress upload notice and copy-URL action, while other files in the same bulk upload continue normally. Existing images are indexed gradually, so visual matching may be incomplete until indexing has progressed.

Replace Existing Media

Enable Enable Media Replace in the plugin settings to show the Replace media action in the Media Library. Users who can upload files and edit the selected media item can choose a replacement and select how it should be applied:

  • Replace the file only keeps the existing filename, URL, and folder. The replacement must have the same file type.
  • Replace the file, use the new file name, and update all links applies the uploaded filename and updates matching references in WordPress content and metadata. Links on external websites are not changed.

The attachment ID is retained in either mode. Under Upload Destination, choose whether to use today’s date or keep the existing media date. When using a new filename, this choice also determines the upload folder.

Installation

Modern Installation

  1. Go to WordPress Dashboard → Plugins → Add New Plugin.
  2. Search for Duplicate Media Guard.
  3. Click Install Now.
  4. Activate the plugin.

Manual Installation

  1. Upload the plugin folder to the /wp-content/plugins/ directory.
  2. Go to Plugins in your WordPress dashboard.
  3. Activate Duplicate Media Guard.

FAQ

How do I replace media in WordPress without changing the URL?

Install Duplicate Media Guard, go to Settings → Duplicate Media Guard, and enable Enable Media Replace. Then open your Media Library, click on a file, and select Replace media. Choose Replace the file only to keep the existing filename and URL. The attachment ID is always preserved.

How do I enable media replace in WordPress?

Enable the Enable Media Replace option in the plugin settings page (Settings → Duplicate Media Guard). A Replace media action will appear in the Media Library for each file you can edit.

Can I replace a media file and update all links automatically?

Yes. When replacing, choose Replace the file, use the new file name, and update all links. The plugin will apply the new filename and update all matching references stored in WordPress posts, pages, and metadata automatically.

What is considered a duplicate?

Images can match by filename, exact content hash, or perceptual hash. Perceptual matching is intended to identify resized or recompressed copies and may also flag visually similar images.

What happens if a duplicate is detected?

With Enable Image Hash Checks on, the uploader shows matching images with previews and lets you cancel or choose Upload anyway. With it off, filename duplicates are skipped and shown through the standard WordPress upload notice.

Can I compare filenames without extensions?

Yes. If enabled, files like photo.jpg, photo.png, and photo.webp are considered duplicates because they share the same filename.

Does duplicate detection change existing media files?

No. Duplicate detection checks files during upload and does not alter existing media. An existing file is changed only when an authorized user explicitly uses the Replace media action.

Can I replace an existing media file and keep the attachment ID?

Yes. Enable Enable Media Replace in the plugin settings, then use Replace media from the Media Library. You can keep the current filename and URL or use the replacement’s filename and update matching links stored in WordPress. The attachment ID is retained in both cases.

Does this work with all media types?

Filename checks and media replace apply to all supported media types. Exact and perceptual hashing apply to images only.

Is the plugin lightweight?

Yes. Fingerprints are computed once and stored with attachment metadata. Existing images are processed in small background batches, so uploads compare hashes rather than repeatedly reading the full Media Library from disk.

Screenshots

Changelog

2.1.1 – 2026-10-28

  • Minor changes and improvements.

2.1.0 – 2026-10-24

  • Added exact image hashing and perceptual similarity detection.
  • Added pre-upload match previews with cancel or upload-anyway options.
  • Added settings switches for duplicate protection and image hash checks.
  • Restored the standard duplicate-upload notice flow when image hash checks are disabled.
  • Added media replace features.

1.0.1 – 2026-09-27

  • Changes: Color & security fixed.

1.0.0

  • Initial release.
  • Prevent duplicate media uploads.
  • Option to compare filenames with file extensions.
  • Option to compare filenames without file extensions.
  • Added admin settings page.
  • Added duplicate upload detection notice.
  • Lightweight and optimized for WordPress Media Library.