WP Media Cleanup helps WordPress sites free disk space by safely removing unused image size variations while preserving original images. Below, you can read about its key features.

Safe and Secure Image Cleanup

The plugin only removes unused image size variations (thumbnails, medium, large, and custom sizes) and never deletes original full-size images. This keeps your originals intact while reclaiming space.

Intelligent Detection System

The scanner checks multiple sources to identify which images are in use:

• Post Content: Scans all published, draft, private, and scheduled posts.
• Widgets: Checks text widgets, media widgets, and custom HTML widgets.
• Customizer Settings: Scans header images, background images, site logos, and theme mods.
• Custom Fields: Detects images in post meta, including page builder data (SeedProd, Elementor, Beaver Builder, etc.).
• Serialized Post Meta: Recursively scans serialized post meta in batches, catching attachment IDs and URLs stored inside ACF repeater fields and other page builder data that a simple text search would miss.
• Term Meta: Checks term meta for attachment IDs stored outside post meta, including WooCommerce category thumbnails.
• Theme Files: Scans the active theme’s PHP, CSS, and JSON files (and the parent theme, if a child theme is active) for hardcoded references to images in the uploads directory.
• Responsive Images: Automatically protects image sizes used in WordPress srcset attributes for responsive images.

This reduces false positives and avoids deleting images that are actually in use.

Always-On Safety Features

Safety features are always enabled and cannot be disabled:

• Automatic Backups: Every deletion creates a backup before removal.
• 30-Day Recovery Window: Files are moved to a temporary directory (soft delete) before permanent deletion.
• Backup Restoration: Restore individual backups or bulk restore all backups with a single click.

Performance Optimizations

Built for large sites:

• Phase 1 Optimization: Builds lookup tables once, converting 60,000+ individual checks into O(1) lookups.
• Resumable Chunked Scan: The scan runs in three stages, each processed in small chunks over AJAX: building the used-images list, running detection steps (widgets, customizer, custom fields, theme files), then comparing attachments against the results. If a scan is interrupted, it can be resumed rather than started over.
• Batch Processing: Configurable batch sizes (default: 25) to prevent PHP timeouts.
• Database Indexing: Indexed columns for efficient querying.
• N+1 Query Prevention: Single queries with in-memory lookups instead of repeated database calls.

Comprehensive WP-CLI Support

Full command-line automation:

# Find and review unused variations
wp media-cleanup find_unused --format=table

# Delete them with confirmation
wp media-cleanup delete_unused --yes

# Check statistics
wp media-cleanup stats

Detailed Audit Logging

Complete audit trail:

• Action Logging: Every deletion, backup, and restore is logged with timestamps.
• Metadata Storage: Stores original file metadata for accurate restoration.
• Configurable Retention: Set log retention period (1-365 days, default: 30 days).
• Automatic Cleanup: Daily cron job removes old log entries based on retention policy.

Automated Maintenance

Daily cron jobs handle routine maintenance:

• Expired Backup Cleanup: Automatically removes backups older than the retention period (default: 30 days).
• Log Cleanup: Removes old log entries based on configured retention policy.

Flexible Configuration Options

• Backup Retention: Configure how long backups are kept (default: 30 days).
• Log Retention: Set audit log retention period (1-365 days).
• Scanning Options: Enable/disable scanning of posts, widgets, customizer, custom fields.
• Image Size Preservation: Choose which image sizes to always preserve (default: thumbnail and full; thumbnail and full specifically can’t be unchecked, since the plugin treats them as required).
• Batch Size: Configure batch processing size for optimal performance.

WP Media Cleanup provides a safe, efficient way to clean up unused image variations on WordPress sites. With always-on backups, intelligent detection, performance optimizations, and security hardening, it’s suitable for sites of all sizes, from small blogs to enterprise installations with millions of files.

The plugin balances automation and safety, giving you control while protecting your media files through automatic backups and a 30-day recovery window. Whether you use the WordPress admin interface (including its Dashboard and History tabs) or WP-CLI commands, WP Media Cleanup helps you reclaim disk space without risking your valuable images.

For removing the unused variations this guide describes, see Removing Unused Media Files using WP Media Cleanup.

If a file was removed and needs to come back, see How to recover files removed with the WP Media Cleanup plugin.