About this plugin
Media Library Cleaner scans your WordPress media library and identifies which files are actually in use and which are safe to delete, so you can clean up your uploads folder with confidence.
0 is a ground-up rebuild from the original release, with a new scanning architecture and admin interface.
How The Scanning Engine Works
Unlike lightweight scanners that only check the post_content column, Media Library Cleaner performs a deep inspection across your entire WordPress architecture. When a scan is initiated, every attachment in the media library is checked against:
- Core Content: Standard post content and Gutenberg block editor attributes.
- Post Meta: All custom fields and metadata, including complex data structures generated by Layout & Design plugins like Elementor and Beaver Builder.
- Theme Settings: Theme mods, site icons, custom logos, and custom header images.
- Taxonomies & Users: Term meta and user meta fields.
- Widgets: Media widgets deployed across sidebars and footers.
- Scan Options: Administrators can explicitly choose whether to include or ignore draft posts and post revisions during the reference check.
Batched Processing Architecture
To handle enterprise-scale WordPress installations, the scanning engine uses batched processing. Instead of loading the entire database into memory, the plugin queries and processes content in strict batches. This architecture prevents PHP memory exhaustion and server timeout errors – and has been thoroughly stress-tested on environments containing over 60,000 posts.
A live four-phase progress bar tracks the execution in real-time, displaying counts for:
- Initialisation
- Post scanning
- Metadata scanning
- Results loading
Results Dashboard
Once the scan completes, results are loaded into a split-view dashboard separating Unused Files from Used Files.
- Used Files View: Explicitly lists the specific posts, pages, or settings where an attachment is currently referenced, giving you absolute certainty about why a file was flagged as active.
- Progressive Card Grid: Files are displayed in a visual grid showing the image thumbnail (or a specific file type icon for non-images), filename, file type, file size, exact pixel dimensions, and upload date.
- Sticky Selection Bar: A persistent control bar tracks the total number of selected files and calculates their combined file size in real-time, allowing you to see exactly how much server space you are about to reclaim. Includes bulk select/deselect controls.
- One-Click Selection: Clicking anywhere on a progressive card toggles a highly visible selected state (blue border and checkmark overlay).
Deletion Mechanics & Safety Protocols
Media Library Cleaner treats data destruction with the utmost caution. A prominent backup warning is displayed before any scan or deletion sequence can be initiated.
- WordPress Capability Checks: Before attempting to remove any file, the plugin performs a strict, per-item capability check. Deletion requests are automatically refused for any file the current user does not have explicit permission to delete.
- Confirmation & Permanence: A WordPress-native confirmation modal intercepts the deletion trigger, explicitly warning the user that deletions are permanent (unless the MEDIA_TRASH constant is enabled in wp-config.php ).
- Batched Deletion: Much like the scanning process, file deletion is handled in batches with a live progress indicator.
- Post-Deletion Reporting: A completion modal provides a definitive summary, explicitly detailing how many files were successfully deleted and how many failed.
- Per-File Reporting: Every individual file is reported as a success or a failure, with specific technical reasons provided for any failed deletions.
Persistent Logging & Environment Data
- Database Session Logs: Every deletion run is permanently recorded in the database. This log records the timestamp, the user who initiated the action, the total file count, and the explicit success/failure results for every individual file processed during that run.
- Environment Info Tab: A dedicated diagnostic tab provides administrators with critical context before running a scan. It displays the total media count, the physical size of the uploads folder, a list of all registered image sizes, the precise uploads directory path, directory writability status, media trash status, and current PHP/WordPress environment details.