Nova Media Cleaner - Duplicate Finder, Clean Unused Images & Media Library Optimizer

Nova Media Cleaner is a safety-first media library cleaner and optimizer for WordPress. It finds exact duplicate images, detects unused files sitting in your uploads folder, and repairs media references that point at files that no longer exist, so your Media Library stays small, fast and free of clutter. Nothing is deleted behind your back. Every scan is read-only. Every deletion starts with a side-by-side comparison and a confirmation step. You always see what is about to change before it changes. What does it do?

• Finds exact duplicate images using cryptographic hash matching, so two files are only called duplicates when they are identical, byte for byte.
• Finds unused media that is not attached to or referenced by anything on your site.
• Repairs broken media references, including the Elementor SVG icons that quietly render blank after a migration or import.
• Protects your content by remapping references from a removed duplicate to the file you keep, so posts and pages do not end up with broken images.

Who is it for? Site owners, agencies and developers who manage sites that have grown over the years, been migrated between hosts, been rebuilt with a page builder, or collected thousands of uploads that nobody can account for.

1. In your WordPress admin, go to Plugins > Add New and search for "Nova Media Cleaner". Click Install Now, then Activate.
2. Or upload the nova-media-cleaner folder to the /wp-content/plugins/ directory, then activate it from the Plugins screen.
3. Go to Media > Nova Media Cleaner and click Start Scan.
4. Review the results. Open the comparison modal to inspect any duplicate before you act.
5. To check for broken pages after a migration, open Broken Media References and run the scan.

It is a good idea to take a full site backup before any bulk cleanup on a production site.

1.4.2

• Enhancement: Modern, gentle review prompt card with smart dismiss logic.
• Fix: Resolved layout notice visibility inside custom dashboard.
• Compliance: Removed rating steering language for WordPress.org review guidelines.

1.4.1

• Improved: on the Broken Media References screen, the File, Issue and Repair columns were squeezed together in the middle of the table with large empty gaps on either side. The columns are now sized for what they actually hold.
• Improved: the smaller lines of text in that table (the page's location, "was ID ...", and the notes under Issue and Repair) now read in the same style as the summary line above the table, instead of the tighter label style they were using.
• Improved: rows that cannot be repaired automatically showed only a dash under Actions, which left you with nowhere to go. They now offer an "Open Page" button so you can go and deal with the reference yourself. The page name in the first column has always opened the editor - it now looks like the link it is.

1.4.0

• New: Broken Media References - a new screen that finds pages whose images and icons point at a Media Library item that no longer exists, and puts them back with one click.

Why this happens: when media is re-imported or a site is migrated, your files often come back with new internal IDs while your pages still point at the old ones. Elementor draws uploaded SVG icons from that ID alone - it ignores the image address stored next to it - so those icons quietly render as empty space even though the file is sitting right there in your library. Nothing in WordPress warns you, and clearing caches does not help. The scan is read-only and tells you two different things apart: icons that are not showing at all on your site right now, and references that are stale but still visible (they happen to load from their address, so nothing looks wrong yet). For each one it finds the same file in your library and offers to repoint it. If the image is only in the Trash it says so and sends you to restore it instead, and if the file is genuinely gone it tells you a backup is needed rather than guessing. Nothing is changed until you click Repair on a specific item, and only that one reference is touched. * Fixed (important): under Settings > Clean Library Scan, the "Attached Images - Consider as In Use" switch did nothing. The scan always treated attached media as being in use no matter how the box was set - and because the box started unticked, it was telling you the opposite of what was happening. The switch now works, and it starts ticked, which is what the scan was already doing. Existing sites carry on exactly as before; only unticking it yourself changes anything. Untick it if your site attaches every upload to a post automatically, so that "attached" does not really mean "in use" - the scan will then examine attached media too. * Fixed: "Reset all options" left the previous scan results cached, so the Unassigned list could keep showing what it found under the old settings. Saving settings already did this correctly; resetting now does too. * Fixed: messages on the Settings screen appeared in the browser's own grey pop-up - the plain box with your domain name at the top - instead of the plugin's own dialog. This was most visible when activating a licence: a refused key came back looking like a browser warning rather than part of the plugin. Every dialog in the plugin now uses the plugin's own styling, on every screen. * Compatibility: the Settings screen used one jQuery function that has been removed in jQuery 4. Nothing was broken on a normal WordPress site, but on a site already running the newer jQuery the settings tabs would have stopped switching. The plugin no longer depends on it. 1.3.0

• Fixed (important): Duplicate Cleaner could list images that are not duplicates at all. Its "visual match" feature compares a small thumbnail of each image, and images without much left-to-right detail - a plain background, a solid colour, a transparent icon, a top-to-bottom gradient - all ended up looking identical to it. A 36x36 icon could be offered as a duplicate of a 1920x1104 banner. Visual matching now ignores images it cannot compare reliably, checks that the two images are the same shape, and confirms every visual match by comparing the actual pictures pixel by pixel before showing it to you. Exact (byte-for-byte) duplicate detection was never affected.
• Added: the comparison window and the results list now tell you HOW each duplicate was matched - a green "Exact copy" (the two files are byte-for-byte identical) or an amber "Visual match" (a similar-looking file, worth a quick look before deleting).
• Changed: "Select All" no longer ticks visual matches. Only exact copies are selected in bulk; visual matches stay for you to review and tick yourself, and you are told how many were skipped.
• Fixed: the comparison window showed "Original Attachment" and a blank date for every original. It now shows the original's real file name, upload date and the post it belongs to, so you can actually tell the two files apart.
• Fixed: if a file was ever replaced with a different file of exactly the same size (some image optimizers and "replace media" plugins do this), the plugin kept using the old file's fingerprint and could pair two completely different images together. It now also checks the file's modification time. Your first scan after updating will be a little slower while fingerprints are refreshed once.
• Fixed: choosing a larger page size in Duplicate Cleaner (for example 50 per page) could snap back to an odd number like 19 and then stay there. The page size you pick is now always respected. On a freshly scanned site a few rows may briefly show "Not checked yet" in the Issue column instead of a usage result - those fill in by themselves as you browse.
• Fixed: when a duplicate was removed, image links stored in widgets, Customizer settings and theme option panels were left pointing at the deleted file. They are now updated to point at the original, and this is done in a way that cannot corrupt those settings.
• Added: if a duplicate is referenced from another plugin's own database table - something this plugin cannot safely rewrite - deletion now stops and tells you exactly which table and column, instead of deleting and leaving a broken image behind. You can still choose "Delete Anyway".
• Added (important): Unassigned Media now finds images that are only ever referenced by their web address, with no link back to the Media Library. That covers images used as a CSS background inside a page builder's generated stylesheet, images stored in another plugin's own database table (job boards, directories, listing plugins), and images set through Appearance > Customize > Additional CSS. Before this, images like these could be reported as unused and deleted while they were still on your site.
• Added: before anything in Unassigned Media is deleted, the plugin now also searches your active plugins' and current theme's own files for a reference to it. This catches an image hardcoded into a plugin's shipped CSS or PHP template - something no database check can ever see. If it finds one, nothing is deleted and you are shown the exact file and line.
• Added: both Duplicate Cleaner and Unassigned Media now show when they were last scanned, and warn you when your media library has changed since - with a "Re-Scan Now" button right there. First-time users also get a clear starting screen instead of an empty table that looks like an error.
• Improved: Unassigned Media now re-checks every file at the moment you delete it, not just when the scan ran. If a file was put to use after your last scan, it is kept and named in the summary instead of being deleted from an out-of-date list.
• Fixed: the deep "check plugin and theme files" verification that runs before deleting unassigned media could quietly run out of time and report nothing found, which looked exactly like a clean result. If it cannot finish, it now says so and deletes nothing until you decide.
• Fixed: when checking whether an image is used inside another plugin's database table, only the first 5,000 rows were examined. On larger sites - a job board, directory or catalogue with more entries than that - images used further down the table looked unused. The whole table is now checked.
• Improved: images used inside page builder layouts are now detected even on sites where the internal usage index is out of date (after an import or migration, for example), and the usage list names the exact page using them.

1.2.22

• Fixed: the Plugins list could keep showing "Pro Active" even after Nova Media Cleaner Pro was deactivated or deleted, since that badge only checked for a valid license and never checked whether the Pro plugin was actually still installed and running. It now correctly reflects both.

1.2.21

• Permanent fix: added a "Media Usage Index" - the plugin now keeps a small, always-current record of which of your posts/pages use each media file, instead of re-scanning your whole site's content every single time it needs to check. This makes "is this image in use?" checks instant, and fixes several problems this caused on content-heavy sites (especially ones using a page builder like Elementor): the Duplicate Cleaner scan taking several minutes, and its results occasionally failing to load right after a scan ("Results could not be loaded"). It builds itself automatically in the background the first time you update (no setup needed), and you can see its status or trigger a manual rebuild from NMC Settings > Advanced.
• Fixed: an image used only through a theme's own "Theme Options" panel (a custom logo, favicon, or background image set outside WordPress's built-in Customizer) wasn't recognized as "in use" - it could be incorrectly flagged as Unassigned and deleted. It's now correctly detected and protected.
• Fixed: the "Last scanned X ago" note on the Duplicate Cleaner and Unassigned Media screens used to stay stuck on its old value until you reloaded the page, even right after a fresh scan had just finished.
• Improved: Unassigned Media now shows the same live scanning progress bar (timer, percentage, and a Stop button) as the Duplicate Cleaner, instead of a plain "Scanning..." message.
• Improved: stopping a scan early now shows the same confirmation popup used elsewhere in the plugin, instead of a small notification that was easy to miss.
• New: the Duplicate Cleaner and Unassigned Media file lists now show who uploaded each file, plus quick "Copy URL" and "Download file" buttons for every item.
• Fixed: the "Errors only" checkbox in the Activity Log viewer (NMC Settings > Logs & Debug) didn't match the rest of the plugin's styling.

1.2.20

• Fixed: clicking "Delete All"/"Delete Selected" duplicates could run into the same unbounded-request risk as other bulk actions on a very large batch - it's now processed in safe, resumable steps like the rest of the plugin's bulk actions.
• Improved: the Activity Log viewer (NMC Settings > Logs & Debug) now has an "Errors only" filter and color-coded entries, plus a "Copy Log" button, making it much easier to spot real problems instead of scrolling through routine entries.
• Improved: log entries are now tagged by severity internally, so the log viewer's error filter reliably catches every real warning/error instead of just fatal crashes.

1.2.19

• Fixed: choosing a higher "items per page" option (250+) on Unassigned Media didn't actually apply - results still spread across extra pages as if a much lower number had been chosen.
• Fixed: clicking "Re-Scan Unassigned" could get stuck and never finish, appearing to restart itself over and over instead of completing.
• Fixed: on sites using a page builder like Elementor with large per-page data, the Unassigned Media scan could take much longer than expected on a single step.
• New: Unassigned Media now shows your last scan results instantly when you open the tab (with a "Last scanned X ago" note), instead of re-scanning every time - a re-scan is only run automatically the very first time, and a "Re-Scan Now" option appears if the results start to look stale.

1.2.18

• Fixed: the Unassigned Media and Duplicate Cleaner screens could bind every button/tab/search click handler twice on a single page load, causing each action to fire its AJAX request twice - on the Unassigned Media screen this could exhaust the request rate limit within seconds and show a "Rate limit exceeded" error.
• Fixed: the "items per page" dropdown on the Unassigned Media screen stopped opening (a leftover duplicate click handler was canceling out the toggle).
• Fixed: opening the Unassigned Media screen for the first time could run a full, uncapped scan synchronously and time out on large media libraries - it now always uses the same safe, batched, progress-bar scan path as a manual re-scan.
• Improved: the Unassigned Media results cache now stays valid for 20 minutes instead of 5, so switching tabs or reloading the page doesn't re-trigger a scan as often.
• Fixed: a duplicate's "in use" status could occasionally be silently overwritten back to stale data if a slow background self-heal pass finished after a delete/restore happened on the same duplicate.

1.2.17

• Fixed: the "items per page" selector on the Duplicate Cleaner could apply the wrong page size or show an incorrect number of pages.
• Fixed: viewing which posts a duplicate is used in could be slow to load, especially on sites using a page builder like Elementor.
• Improved: "Automatic Scans" is now enabled by default, so new installs get a weekly background duplicate check without any setup.
• New: the dashboard now shows how long ago your last scan was, and suggests a re-scan if it's been a while or a lot of new media has been added.
• New: if Automatic Scans is off, you'll now see a one-click option to turn it on after your first scan.
• Fixed: a Pro upgrade screen was showing a broken-looking icon next to "Already have a License Key?".

1.2.16

• Permanent fix: the Duplicate Cleaner's tab/filter/search AJAX endpoint and the counts recalculated after any delete/restore/ignore action had the same unbounded per-duplicate database queries the dashboard page itself had in 1.2.11 - now fixed the same way (bulk queries instead of one-by-one, cached usage status).
• Permanent fix: on sites using a page builder (Elementor, Divi, WPBakery, Avada, Beaver Builder) with large per-page saved data, the "is this image in use" check could take several seconds per image because it was scanning the same large page-builder data twice. It's now scanned once, and any single field larger than ~500KB is skipped rather than scanned in full, so this can no longer stall a page load.
• Permanent fix: any duplicate whose "in use" status hasn't been computed yet (from a scan run before 1.2.11) now gets it computed and permanently saved the moment it's first checked, instead of being recalculated on every page view - so even on a slow site, this can only ever be slow once per duplicate, never twice.
• Permanent fix: computing "in use" status for newly found duplicates during a scan (manual or scheduled Auto-Scan) is now time-budgeted like the rest of the scan, so a batch that happens to find several duplicates on a page-builder-heavy site can no longer make the scan itself time out.
• Added a fatal-error log: if anything still goes wrong while rendering an admin page or handling a request, it's now recorded in the plugin's own Activity Log (NMC Settings > Logs & Debug) so an issue can be diagnosed without needing WP_DEBUG or server log access.
• Fixed the Activity Log's "View Log" button and log viewer, which were missing from the Logs & Debug screen entirely (the underlying feature existed but had no way to display it).

1.2.11

• Permanent fix (follow-up to 1.2.10): the Duplicate Cleaner's "in use" check for each duplicate is now computed once during the scan itself and cached with the results, instead of being recalculated from scratch on every dashboard page view. This removes the risk of a timeout entirely instead of just capping it, and also makes the dashboard noticeably faster to load on sites with many duplicates.
• Permanent fix: the Unassigned Media deep-scan (which checks every candidate file against posts, pages, products, widgets, etc.) now runs as a background batched scan with a progress indicator instead of a single long-running request, so it can never hit a server or PHP timeout no matter how large the media library is.

1.2.10

• Critical fix: the Duplicate Cleaner dashboard could time out (504 Gateway Timeout / blank white screen) on real sites with a meaningful number of duplicates or a large database, because it ran several expensive usage-lookup queries for every duplicate on every page load just to compute filter-tab counts. This is now capped so the page always loads.
• Fixed the new Unassigned Media "unused files" teaser running a full, uncapped deep scan synchronously on every page load (also capable of timing out large libraries) - it now loads asynchronously via AJAX using a lightweight query, after the page itself has already rendered.
• Hardened the Duplicate Cleaner dashboard against a fatal error if a helper function is ever unavailable (e.g. due to a stale PHP opcode cache after an update), so a Pro-badge display issue can never take down the whole page.

1.2.9

• Fixed duplicate scan reliability: ties in the scan order no longer cause real duplicates to be silently skipped, and duplicate/unassigned usage checks now consistently ignore trashed posts.
• Added optional Near-Duplicate (perceptual hash) detection alongside exact hash matching.
• Added a first-run empty-state screen for the dashboard instead of a blank/confusing scan view.
• Added an Ignore/Unignore option for duplicate items, matching the existing Unassigned Media workflow.
• Added a "Recently Optimized" list with 1-click Restore and pagination to the Image Optimization tool.
• Free tier deletes now use WordPress's own native Trash (instead of permanent delete), so accidentally removed media stays recoverable for 30 days without needing any Pro upgrade.
• Pro's Staging Trash now supports an automatic retention/auto-purge policy with a configurable "Trash Retention (Days)" setting, so trashed items don't accumulate forever.
• Fixed the Trash tab showing an incorrect count/empty mismatch, and added a clear "Pro Feature" lock screen (instead of a generic "No items found") when a Free user opens the Trash tab.
• Fixed the Pro crown/badge icon incorrectly appearing on licensed Pro sites that had "Skip Trash" enabled.
• Hardened license checks across Unassigned Media, Media Renamer, and Bulk Alt Text so these remain properly gated on an active Pro license rather than just the Pro plugin being installed.
• Removed the sticky footer bar; "Official Website" and "Documentation" links now live in the header.
• Simplified the Settings page by removing several non-functional legacy options, and wired up real behavior for Images Only, Skip Trash, Hide Thumbnails, and Warning Message.
• Various WP-CLI command fixes to prevent fatal errors on optimize, restore-image, and generate-alt.
• Fixed the Pro Filesystem Orphaned Scanner permanently deleting files with unlink() instead of routing through Staging Trash like every other module - orphaned files are now recoverable too.
• Fixed the daily Pro license re-validation check (refund/cancellation detection) never actually running - it is now properly scheduled.
• Added an optional Scheduled Auto-Scan (Settings > Advanced): runs a duplicate scan automatically on a daily or weekly schedule, with an optional email report.
• Added a languages/nova-media-cleaner.pot translation template.
• Added the missing "Filesystem Scan" admin page - the Pro Filesystem Orphaned Scanner had a working backend but no menu item or page to access it from.
• Fixed several "No items found" empty states (Unassigned Media Trash tab, Bulk Alt Text, Recently Optimized list) that lost their table header or showed no message at all.
• Fixed wp nova-cleaner license deactivate never releasing the activation slot on the license server, and license activate not storing the instance ID needed to release it later - both could leave a license "stuck" as used up on an old site.
• Fixed wp nova-cleaner license status printing the full license key in plaintext for inactive/expired licenses.
• Added logging and clearer messaging around license activation/deactivation so support can diagnose "Pro suddenly turned off" reports.
• Removed a dead, unreachable legacy license activation/deactivation code path in the Settings page controller that used an outdated hash formula and none of the safeguards above.
• Removed the unused "Deactivation Feedback" modal and its wipe-data trigger - it was disabled on plugins.php years ago (it once blocked deactivation for every plugin, not just this one) and had no working replacement, so it never actually appeared to users.
• Fixed a leftover reference to the removed "buffer settings" in the Help & Support page's documentation blurb.
• Fixed Image Optimizer's 1-Click Restore only reverting the full-size image after a WebP conversion, leaving every thumbnail size permanently converted with a broken backup lookup.
• Fixed Image Optimizer marking a failed optimization (missing file) as done, permanently skipping that image from all future optimize batches.
• Fixed automatic WebP conversion on upload never creating a backup, regardless of the "Enable Backups" setting - those images could never be restored.
• Added a free-tier teaser on the Unassigned Media screen showing how many unused files and how much storage they're wasting, so you know what you'd get before upgrading.
• Cleaned up internal CSS class naming and code comments that referenced a competing product.
• Disclosed the Lemon Squeezy license-server connection used by Pro License Activation in this readme, per the plugin directory's external services requirement.

1.2.7

• Bundled local Roboto font files inside plugin assets for 100% GDPR compliance, privacy, and faster loading.
• Removed external Google Fonts API dependencies.
• Updated admin UI typography to use local Roboto fonts.

1.2.6

• Added usage detection for ACF & Custom Post Meta fields.
• Added usage detection for popular Page Builders (Elementor, Divi, WPBakery, Avada, Beaver Builder).
• Added Theme Settings, Site Logo, and Favicon usage detection.
• Enhanced plugin deactivation cleanup handler.

1.2.5

• Fixed plugin deactivation popup window freeze on plugins page.
• Enhanced deactivate/disable action link detection and JS redirection fallback.
• Improved database cleanup handler execution flow.

1.2.4

• Fixed Start Advanced Scan event handler and lock clearing mechanism.
• Added custom number input for Unassigned Media batch cleanup limit.
• Full-screen wide Image Comparison modal with full admin dashboard backdrop blur.
• Optimistic UI row deletion for instant media cleanup response.
• Fixed plugin deactivation popup for managing database settings cleanup.

1.2.3

• Added interactive deactivation popup modal.
• Added option for users to cleanly remove database settings and temporary files upon deactivation.

1.2.2

• Code refinement and stability improvements.

1.2.1

• Fixed single card "Delete Copy" button JS handler to open confirmation modal instead of failing silently.
• Added dynamic warning modal title and custom confirmation text for non-in-use duplicate deletions.
• Replaced raw emoji status indicators (green and amber dots) with modern CSS micro-status badges (Emerald & Amber pills).
• Enhanced "Delete Copy" button contrast with high-visibility trash icon and smooth hover micro-animations.

1.2.0

• Removed all limitations and made all features fully functional.
• Performance & memory optimization during scans.
• Progress bar UI improvements.

1.1.0

• Added Comparison Modal.
• Local ZIP backups.
• Paginated results.

1.0.0

• Initial release.