Broken Media Inspector finds the broken images in your WordPress Media Library, tells you exactly which posts and pages use them, and clears out the orphaned files left behind in your uploads folder. It is free and unlimited — no paid tier, no row caps, and no external services.
The problem it solves
After a migration, a restored backup, or a change of host, images go missing. WordPress still lists them in the Media Library, but the file is gone from disk — so you get broken images scattered across your site with no easy way to find which pages are affected. Meanwhile the opposite problem builds up quietly: your uploads folder fills with files that nothing references any more.
Broken media
The plugin scans every item in your Media Library and reports which images are broken — either the file is missing from disk, or its metadata is incomplete. For each one it shows you the posts, pages, galleries and featured images that use it, with direct edit links, plus the likely cause and how to fix it.
Missing files are grouped by folder, so a whole missing directory appears as a single line rather than hundreds of separate rows. That is usually the fastest way to spot a migration that dropped a folder. Results export to CSV.
Scanning runs in two phases — a fast pass that checks every file on disk, then a background pass that works out usage for the broken items only. Thousands of images scan in seconds. The broken-media scan is read-only and changes nothing.
Orphaned files
Over time wp-content/uploads collects files that are no longer in the Media Library: leftovers from deleted posts, failed imports, and manual uploads. Broken Media Inspector finds them, shows how much space they take, and lets you either register them back into the Library, or archive them.
Archiving is safe and reversible. Nothing is deleted straight away — files move (with their folder structure intact) to wp-content/archive. You archive what you think you do not need, check the site still looks right, and only then empty the archive. Changed your mind about a file? Restore it in one click. Generated thumbnails are recognised and never mistaken for orphans.
Features
- Broken image detection — missing files and incomplete metadata
- Folder grouping — whole missing directories summarised in one line
- Usage mapping — featured images, blocks, galleries and direct URLs, with edit links
- CSV export — hand the report to a colleague or keep it on file
- Orphaned file scanner — find unregistered files in your uploads folder
- Safe archive workflow — archive, verify, then delete or restore
- Import orphans — add unregistered files back into the Media Library
- Thumbnail-aware — generated sizes are never flagged as orphans
- Two-phase scanning — fast results even on large libraries
- No configuration, no external services, no paid tier
Getting started
- Upload the plugin folder to
/wp-content/plugins/, or install the zip from Plugins → Add New → Upload Plugin. - Activate it through the Plugins menu.
- Go to Tools → Broken Media Inspector.
- Click Scan Media Library.
Start with the broken-media scan — it is read-only, so you can run it safely on a live site to see what is wrong before changing anything. Every file action is limited to administrators and validated to stay inside your uploads or archive folder.
Requirements
- WordPress 5.0 or later
- PHP 8.2 or later
Support
Questions and bug reports are welcome — get in touch via thebigcity.co.nz. The source lives on GitLab.
The plugin is free and always will be. If it saved you an afternoon of hunting down broken images, you can buy me a coffee.