XeroWP
UploadSleuth – Media Audit & Cleanup
UploadSleuth – Media Audit & Cleanup

UploadSleuth – Media Audit & Cleanup

0/5 (0 ratings) — active installs Updated Sep 14, 2026
auditcleanupmediauploadswp-cli
Download v1.1.0

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.