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.