UploadSleuth – Media Audit & Cleanup

UploadSleuth reconciles files in the uploads directory against WordPress attachment metadata and database references.

Files without a detected reference are shown as likely stray candidates. They are not declared safe to delete. The plugin encourages a review, dry-run, and quarantine workflow before permanent removal.

Features

• AJAX-powered dashboard under Tools > UploadSleuth.
• Scan summaries including candidate count and potential disk space.
• Persistent storage-impact statistics for reclaimed space and completed cleanup actions.
• Search, sorting, bulk selection, and per-user saved results.
• Dry-run, timestamped quarantine, verified backup-and-remove, and guarded deletion.
• Recognition of attachment originals, generated sizes, edited originals, and backups.
• Checks for references in posts, metadata, options, and configured custom tables.
• Optional non-core database table scanning.
• WP-CLI table, CSV, JSON, and YAML output.
• CLI age and size filters, CI mode, and explicit permanent-delete confirmation.
• Complete in-dashboard WP-CLI reference with copy-ready recipes.
• Optional last-moment attachment and database revalidation, enabled by default.
• Configurable scan/action batches and pauses for slow servers.
• WordPress-native standalone-file deletion through wp_delete_file().
• Stoppable batched scans that preserve reviewed partial findings.
• Separate Media Library integrity checks for missing originals and generated image sizes.
• WordPress-native cleanup of reviewed missing-file attachment records.
• No external service or telemetry.

Important safety note

A file can be referenced by an external system, theme or plugin code, encoded data, a custom database, or another location the plugin cannot inspect. Make a verified backup and test quarantined files before deleting anything permanently.

UploadSleuth is maintained by the same developer behind Notificator – Alerts & Notifications, a WordPress plugin for turning site events into dashboard alerts and optional mobile or MQTT notifications. Browse the UploadSleuth source code on GitHub.

WP-CLI Examples

wp upload-sleuth

wp upload-sleuth --uploads-subdir=2025 --format=json

wp upload-sleuth --older-than=90 --min-size=100 --summary-only

wp upload-sleuth --quarantine --dry-run

wp upload-sleuth --delete --dry-run

wp upload-sleuth --backup-delete --dry-run

Real permanent deletion requires wp upload-sleuth --delete --yes. A real backup-and-remove operation similarly requires wp upload-sleuth --backup-delete --yes.

Long scans can be checkpointed and resumed:

wp upload-sleuth --state-file=/path/upload-sleuth-scan.json
wp upload-sleuth --resume --state-file=/path/upload-sleuth-scan.json
wp upload-sleuth --clear-state --state-file=/path/upload-sleuth-scan.json

Use --save-report=/path/upload-sleuth-report.json to export JSON findings, then import that file from the WP-CLI tab in the dashboard. Interactive table scans display an animated progress bar.

Integration hooks

UploadSleuth fires upload_sleuth_* lifecycle and file-action hooks for notification and automation integrations, including scan started/completed/stopped, action started/completed, and upload_sleuth_quarantine_emptied. The source argument identifies dashboard or cli. See the project README for the complete hook list.