First public release. Deleting sends media to the trash rather than removing it, every file is re-checked against the full reference search immediately before it is touched, and duplicate resolution re-points every reference - including size variants - before anything is deleted.<\/p>"},"ratings":[],"assets_icons":{"icon-128x128.png":{"filename":"icon-128x128.png","revision":3674493,"resolution":"128x128","location":"assets","locale":"","width":128,"height":128},"icon-256x256.png":{"filename":"icon-256x256.png","revision":3674493,"resolution":"256x256","location":"assets","locale":"","width":256,"height":256}},"assets_banners":{"banner-1544x500.png":{"filename":"banner-1544x500.png","revision":3674493,"resolution":"1544x500","location":"assets","locale":"","width":1544,"height":500},"banner-772x250.png":{"filename":"banner-772x250.png","revision":3674493,"resolution":"772x250","location":"assets","locale":"","width":772,"height":250}},"assets_blueprints":{},"all_blocks":[],"tagged_versions":["1.0.0"],"block_files":[],"assets_screenshots":{"screenshot-1.png":{"filename":"screenshot-1.png","revision":3674493,"resolution":"1","location":"assets","locale":"","width":1440,"height":900},"screenshot-2.png":{"filename":"screenshot-2.png","revision":3674493,"resolution":"2","location":"assets","locale":"","width":1440,"height":900},"screenshot-3.png":{"filename":"screenshot-3.png","revision":3674493,"resolution":"3","location":"assets","locale":"","width":1440,"height":900},"screenshot-4.png":{"filename":"screenshot-4.png","revision":3674493,"resolution":"4","location":"assets","locale":"","width":1440,"height":900},"screenshot-5.png":{"filename":"screenshot-5.png","revision":3674493,"resolution":"5","location":"assets","locale":"","width":1440,"height":900}},"screenshots":{"1":"Duplicate groups, matched on file content rather than filename. The reference count is there because it is the number you weigh up when choosing which copy to keep.","2":"The unused list. Every file here was checked against twelve places first, and the notice is a standing reminder that a database scan cannot read your theme's PHP.","3":"Nothing is deleted without naming the files first. Cancel leaves the library untouched.","4":"Removals go to the trash and stay on disk. Restore puts a file back; emptying the trash is the separate step that actually reclaims the space.","5":"A scan in progress. The log names every file as it goes, so a run that misses something is visible rather than silent."}},"plugin_section":[],"plugin_tags":[3786,238093,233,219749,4574],"plugin_category":[],"plugin_contributors":[278510],"plugin_business_model":[],"class_list":["post-359572","plugin","type-plugin","status-publish","hentry","plugin_tags-cleanup","plugin_tags-duplicate-images","plugin_tags-media-library","plugin_tags-unused-media","plugin_tags-wp-cli","plugin_contributors-ltracy","plugin_committers-ltracy"],"banners":{"banner":"https:\/\/ps.w.org\/media-mage\/assets\/banner-772x250.png?rev=3674493","banner_2x":"https:\/\/ps.w.org\/media-mage\/assets\/banner-1544x500.png?rev=3674493","banner_rtl":false,"banner_2x_rtl":false},"icons":{"svg":false,"icon":"https:\/\/ps.w.org\/media-mage\/assets\/icon-128x128.png?rev=3674493","icon_2x":"https:\/\/ps.w.org\/media-mage\/assets\/icon-256x256.png?rev=3674493","generated":false},"screenshots":[{"src":"https:\/\/ps.w.org\/media-mage\/assets\/screenshot-1.png?rev=3674493","caption":"Duplicate groups, matched on file content rather than filename. The reference count is there because it is the number you weigh up when choosing which copy to keep."},{"src":"https:\/\/ps.w.org\/media-mage\/assets\/screenshot-2.png?rev=3674493","caption":"The unused list. Every file here was checked against twelve places first, and the notice is a standing reminder that a database scan cannot read your theme's PHP."},{"src":"https:\/\/ps.w.org\/media-mage\/assets\/screenshot-3.png?rev=3674493","caption":"Nothing is deleted without naming the files first. Cancel leaves the library untouched."},{"src":"https:\/\/ps.w.org\/media-mage\/assets\/screenshot-4.png?rev=3674493","caption":"Removals go to the trash and stay on disk. Restore puts a file back; emptying the trash is the separate step that actually reclaims the space."},{"src":"https:\/\/ps.w.org\/media-mage\/assets\/screenshot-5.png?rev=3674493","caption":"A scan in progress. The log names every file as it goes, so a run that misses something is visible rather than silent."}],"raw_content":"\n
Media Mage scans your media library for two kinds of clutter:<\/p>\n\n
A tool that deletes files is only as good as the search it runs first, because anything the search misses gets reported as unused and then deleted. Most of the work in this plugin is in that search, and in the guards that sit between the search result and the delete.<\/p>\n\n
Media Mage checks all of the following before it will call a file unused:<\/p>\n\n
_thumbnail_id<\/code>) and the attachment's own post parent<\/li>\n- Site logo and site icon<\/li>\n
- WooCommerce product galleries<\/li>\n
- Oxygen Builder base64-encoded layout data (
_ct_builder_shortcodes<\/code>, _ct_builder_json<\/code>, ct_style_sheets<\/code>, ct_components_classes<\/code>)<\/li>\n- Gutenberg block IDs and
wp-image-N<\/code> classes, so a block that carries an ID and no URL still counts<\/li>\n<\/ul>\n\nEach of those is checked against every URL the attachment can appear under: the full-size file, every generated size variant, the -scaled<\/code> version and the preserved original. Inserting an image at Medium embeds the medium URL and never the full-size one, so checking only the full-size URL is how a live image ends up on an unused list.<\/p>\n\nURLs are also matched in their JSON-escaped form (\\\/<\/code> instead of \/<\/code>), which is how Elementor, Divi and Gutenberg block attributes store them.<\/p>\n\nWhat it cannot see<\/h4>\n\n
Media Mage reads the database. It does not read your code. It will not find:<\/p>\n\n
\n- An image path hardcoded in a theme or plugin PHP file, including a child theme<\/li>\n
- URLs rewritten to an external CDN, so what is stored no longer matches what is served<\/li>\n
- An attachment referenced only by its numeric ID in a custom field.<\/strong> IDs are checked in featured images, WooCommerce galleries, the site logo and icon, and Gutenberg blocks and gallery shortcodes inside post content. Everywhere else the search is for the URL. The common case is an ACF image field set to return the Image ID rather than the URL - that value is a bare number and Media Mage cannot tell it from any other number.<\/li>\n
- Uploads shared or copied between sites on a multisite network.<\/strong> Each scan sees one site. If site A's image is used on site B, site A reports it unused.<\/li>\n
- Anything held in a store the plugin does not know about<\/li>\n<\/ul>\n\n
If your theme prints wp-content\/uploads\/2026\/01\/hero.jpg<\/code> straight out of a template file, that image is reported as unused. Review the list before deleting. There is a wpmj_is_referenced<\/code> filter for protecting files programmatically - see the FAQ.<\/p>\n\nOne more thing worth knowing, because it works the other way: an attachment whose post_parent<\/code> points at a post that still exists counts as referenced. Most images uploaded through the post editor have one, so on a long-lived site the unused list will be shorter than you expect. That is deliberate - it errs toward keeping files - but it is why a scan can come back nearly empty on a site you were certain was full of clutter.<\/p>\n\nHow it avoids breaking your site<\/h4>\n\n\n- Deleting trashes by default.<\/strong> Files go to the WordPress trash. The database rows and the files on disk both survive, so a wrong call is recoverable from the Trash tab. Disk space comes back when the trash is emptied, which is a separate action.<\/li>\n
- Every file is re-checked at delete time.<\/strong> The scan is a snapshot. Scan at 09:00, put one of those images on the homepage at 11:00, click delete at 12:00, and the snapshot is wrong. Each file is checked again immediately before it is touched, and anything back in use is skipped and reported.<\/li>\n
- Deletes are limited to the current scan results.<\/strong> A delete request for an ID that is not in the results is refused, and expired results fail closed rather than waving the request through.<\/li>\n
- Resolving a duplicate re-points references first.<\/strong> Post content, post meta, options, theme mods, WooCommerce galleries and Oxygen data are rewritten to the keeper before the duplicate is removed, including every size variant and the JSON-escaped forms.<\/li>\n
- Serialized data is handled properly.<\/strong> Nested serialized values are rewritten with their length prefixes recomputed at every level. Values containing PHP objects are skipped rather than round-tripped, and any rewrite that will not read back is discarded.<\/li>\n
- Rewrites stay in scope.<\/strong> Cron, rewrite rules, transients and edit locks are excluded by name. A backup plugin's run log that merely names a file is not evidence, and editing it is its own kind of damage.<\/li>\n
- A duplicate group is only a proposal, and the delete verifies it.<\/strong> Groups come from cached hashes, and a cache keyed on file timestamps can be wrong - restoring uploads with rsync or a backup tool changes content while leaving timestamps untouched. Both files are re-hashed immediately before a duplicate is removed, and anything no longer byte-identical is kept and reported instead. If either file cannot be read, that counts as unverified, and unverified is never treated as identical.<\/li>\n
- A duplicate whose references could not all be rewritten is kept, not deleted.<\/strong> Some values cannot be safely rewritten - a serialized PHP object, a structure with an internal back-reference. Those are left alone rather than corrupted, and because leaving them alone means a reference would survive pointing at a deleted file, the deletion is cancelled and the file and rows are named.<\/li>\n<\/ul>\n\n
Other things it does<\/h4>\n\n\n- Trash view.<\/strong> Everything Media Mage trashed is listed on its own tab, with restore and a separate empty-the-trash action. It lists what this plugin trashed, not everything ever trashed on the site.<\/li>\n
- Ignore list.<\/strong> Mark a file as fine and it stops appearing in the unused list. Without this, the handful of files the plugin structurally cannot see references for sit at the top of every scan forever.<\/li>\n
- Where is this used?<\/strong> Each file can show the posts that reference it, with edit links and how the match was made. The queries behind the reference count already knew which posts matched, and that count is the whole basis for deciding which copy of a duplicate to keep, so it is worth seeing.<\/li>\n
- CSV export<\/strong> of the scan results, so there is a record of what was found before anything is deleted.<\/li>\n
- WP-CLI commands<\/strong> for scanning, listing, resolving, deleting, exporting, the ignore list and the trash, with dry runs. Resolving shares one implementation with the admin screen, so the two cannot drift apart. See the FAQ.<\/li>\n
- Two-phase scan with per-file progress, sized so each request finishes well inside a shared host's PHP timeout<\/li>\n
- MD5 hashes cached against file modification time and size, so re-scans are fast<\/li>\n
- Reclaimable-bytes total, plus library total, ignored count and trashed count, so the numbers have a denominator<\/li>\n
- Attachments whose file is missing from disk are counted separately rather than silently hashed as identical<\/li>\n
- Two filters,
wpmj_is_referenced<\/code> and wpmj_replace_query<\/code>, for sites that need the last word<\/li>\n- Uninstall removes every row the plugin wrote, on single sites and across a multisite network<\/li>\n<\/ul>\n\n
Free, and staying that way<\/h4>\n\n