Using Media Deduper Pro: Clean up your Media Library

Before You Begin

We highly recommend that you take Media Deduper for a test run on a staging environment to ensure it works the way you expect. If you don't have access to a staging environment, ensure that you have a backup of your site before using Media Deduper, so if any media are accidentally permanently deleted, there's a way to retrieve them again.

Plan to inspect your content carefully after Smart Deleting anything. If you are using a third-party page builder (like Elementor, WPBakery, Divi, Beaver Builder, etc.), expect your content to need some manual cleanup afterward. Every page builder stores its data in a different way, and some may require more manual intervention than others.

Running a Media Deduper Scan

Log into WordPress as an administrator.

In the left sidebar, select Media > Manage Duplicates.

Then go to the Index tab and click the Index Media button.

Indexing can take a long time since it happens as a background action and depends on hosting resources. Even if the progress bar doesn't appear to move at first, we recommend waiting at least 2 hours for the process to begin. If the progress bar hasn't moved at all after several hours, check out these troubleshooting tips.

Indexing may take anywhere from a few seconds to several days, depending on the size of your media library. When indexing is complete, click the Manage Duplicates Now button to continue.

Removing Duplicate Media Files

You'll be taken to a list of all of the duplicate media files in your WordPress Media Library. To remove a duplicate file, click the checkbox to its left. In the Bulk Actions drop-down above the list, you can select one of two options for deletion.

Delete Permanently

When selected, this duplicate image will be deleted permanently everywhere on your site. 

This means that if the image is in use somewhere - for example, in a blog post - a broken image icon will display on your site because the image will no longer be available. Delete Permanently has the same effect as deleting an attachment from the main WordPress media library screen, except the MEDIA_TRASH constant is ignored (media will always be deleted immediately).

If you select Delete Permanently, you'll receive a pop-up message asking you to confirm that you want to delete the media file:

Click OK. The image will be permanently deleted and you will be returned to the full list of duplicate media.

Smart Delete

When Smart Delete is selected, the duplicate image will be deleted, and references to it will be replaced with references to its related, undeleted duplicate image. The references will be replaced in:

  • <img> tags (including resized versions) in WordPress posts, pages, and other content types

  • Direct links to the image file, e.g. <a href=”/wp-content/uploads/2021/08/image.jpg”>...</a>

  • Gallery shortcodes with enumerated images, e.g. [gallery ids=”123,456,789”]

  • WooCommerce product gallery images

  • Yoast’s Facebook and Twitter images

  • Featured images

  • Images in WordPress's built-in blocks (Image, Media + Text, Gallery, Cover)

  • Images in Advanced Custom Fields fields (File, Gallery, Image, and WYSIWYG fields)

  • Optionally: any other references you define yourself using MDD's filter hooks

Note: If you attempt to delete all copies of the same image, Smart Delete will not let you delete all copies; it will retain the image with the lowest media ID (typically the oldest version) and will use that file for replacement throughout your site, as noted in the list above.

Before proceeding with Smart Delete, use your favorite backup method to back up your entire site (including uploads) first.

If you select Smart Delete, you'll receive a pop-up message asking you to confirm and recommending that you back up your uploads and database:

If you click OK, the selected file(s) will be deleted and you will be returned to the full list of duplicate media.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.