How to Remove Unused Media Files in WordPress Safely

To remove unused media files from WordPress safely, scan the uploads folder against everything on your site that can point at a file, read the evidence for each result and move files to a quarantine instead of deleting them. Media and Database Cleaner for WordPress does this, and its admin menu is labelled Cleanup Scanner. A scan only reads, nothing is removed until you select items and confirm, and quarantined files can be restored until you delete them permanently. One limit to know before you start: the scanner cannot see references from outside your site, so it labels files “Possibly unused” or “Safe to remove”, never plainly “unused”.

What a scan can know, and what it cannot

Before it judges a file, the media scan builds an index of everything on your site that can point at one: posts, pages and other post types, all post meta, options, term, user and comment data, the files of the active theme and active plugins, WooCommerce product and category images, and Elementor layout data. It matches upload addresses, bare file names and attachment IDs, including IDs stored under image-like names such as logo or background. The content of trashed posts, revisions and auto-drafts counts only as weak evidence, so a file used only there is “Possibly unused”.

The scanner knows only what is in your database and in your theme and plugin files. Read these blind spots before you trust a label:

• References from outside the site: another website, a CDN configuration, an email campaign or a bookmarked file address.
• Addresses stored as JSON with escaped slashes: the text search looks for the literal wp-content/uploads/, so JSON written as wp-content\/uploads\/ is not recognised. An image used only that way is normally found only if its attachment ID sits under an image-like name. Block editor content is not affected.
• Addresses built at run time: if theme or plugin code calls functions such as wp_get_attachment_url or the_post_thumbnail, a reference could exist that static reading cannot follow. The evidence then says so.
• Page builders: block editor content is read in full and Elementor has its own reader. WPBakery, Divi, Beaver Builder and Oxygen have none and depend on the general search for addresses and file names. Run the first scan on a staging copy.
• Code and folders it does not read: must-use plugins, theme files over 2 MB and plugin files over 1 MB are not read. A folder counts as a plugin’s only if it is named after the plugin, the plugin’s code names it, or it is in a built-in list of 35, so files in other folders can show as “Safe to remove”. Open Why on folders you do not recognise.
• Meta of deleted or trashed posts: it counts as a live reference, so a featured image set on one stays “In use”. Remove trashed posts you do not need for good, run an Orphan scan to remove orphan post meta, then scan media again.
• Optimiser copies: files such as photo.jpg.webp have no library record, so they can be labelled “Safe to remove”. Untick WEBP and AVIF first.

What you need

• WordPress 6.0 or later and PHP 7.4 or later (tested up to WordPress 7.1).
• A user with the manage_options capability, which WordPress gives to administrators.
• A full backup of your files and database. According to its documentation, the plugin’s own backups cover only what it removes.
• File access that WordPress itself can use, because the plugin moves files through its filesystem class, plus free disk space: quarantined files stay on the same disk.
• A single site. Network activation on multisite is refused, so activate it on each site. On a network’s main site, leave anything under uploads/sites/ alone: it holds other sites’ files, which this scan cannot judge. WooCommerce is optional.

It is a paid plugin, but in the code the scanning, quarantine and restore steps never check the licence; the licence client only provides the licence screen and update checks.

Step-by-step setup

1. Make a full backup of your site files and database.
2. Download the plugin zip under My Account → Downloads on wpexpertshub.com.
3. In WordPress, open Plugins → Add Plugin → Upload Plugin, choose the zip, click Install Now, then click Activate Plugin.
4. Open Cleanup Scanner → Settings. Under File types included in media scans, 28 extensions are ticked by default. If an image optimiser keeps .webp or .avif copies next to your images, untick WEBP and AVIF.
5. Under Recent upload grace period, keep the 30 days or change it. A file newer than this is never labelled “Safe to remove”, and 0 judges every file on the evidence alone. Click Save Changes.
6. Open Cleanup Scanner → Dashboard and click Run Media Scan. If you leave the page, the scan resumes when you return.
7. Open Cleanup Scanner → Media Scanner and click the Safe to remove pill. Open Why on a few rows and check that the evidence makes sense for your site.
8. Tick a small batch, click Quarantine Selected and confirm. Browse your site and check that nothing is missing.
9. Test the way back: open Cleanup Scanner → Cleanup, click Restore on one file and check that it is back at its original path.

How to read the labels

• In use: something on the live site points at it. The row has no checkbox, and the server refuses it.
• Protected: the file sits in the uploads folder of an active plugin, is shared by several library records, or has a twin whose name differs only in letter case. It is never offered.
• Safe to remove: no library record, no reference and no surviving original, such as a loose file, a leftover thumbnail of a deleted image or a file in the folder of a plugin that is no longer installed. Quarantine Selected handles these after a confirmation that needs no typing.
• Possibly unused: a library item that nothing displays, a file used only by trash or revisions, an image uploaded to a post but not shown there, a file in the folder of an inactive plugin, or a recent file held back by the grace period. Quarantine Selected After Review handles these, and you type DELETE.
• Unknown: for a file this means the reference index could not be built. These files cannot be removed, so run the scan again.
• Unreadable: the scan could not read the file. It can still be ticked for review, so check it by hand first.

A library item is judged as a whole: if its ID, its original or any generated size is used, every one of its files stays. An unused library image is therefore never “Safe to remove”. It appears as “Possibly unused” and needs the review route.

What quarantine does and how to undo it

• Plain files: moved to uploads/.cleanup-scanner/quarantine/ with their relative path, and a SHA-1 checksum is recorded.
• Library items: the original, every generated size and the library entry move as one unit. The plugin backs up the entry’s database rows, moves the files, deletes the rows with direct SQL and puts the files back if a step fails. Other plugins that listen for attachment deletion are not told. The image leaves the Media Library until you restore it with the same ID and meta.
• Restore: on Cleanup Scanner → Cleanup, click Restore (Restore attachment for a library item). It is refused if a file already sits at the original path or the quarantined copy no longer matches its checksum.
• Delete permanently: erases the quarantined files from disk, and for a library item its saved entry. It does not use the WordPress Trash and cannot be undone. A single file asks for a confirmation; Delete selected permanently makes you type DELETE. Only now is disk space freed.
• Empty folders: Remove empty folders removes only folders still empty at that moment. There is nothing to restore.

The .cleanup-scanner folder, which holds the quarantine, gets a deny-all .htaccess file that Apache honours where it allows .htaccess files. The plugin writes no rule for servers that ignore it, such as nginx, so there quarantined files can be requested by their address. Add a rule that denies /wp-content/uploads/.cleanup-scanner/.

Database clutter: tables and orphan rows

Cleanup Scanner → Database Scanner lists every table, works out which plugin or theme created it and whether that owner is active. Core tables, this plugin’s own tables and tables of active plugins cannot be selected. For the rest, Back Up & Drop Selected asks you to type DELETE, writes the table to a backup file first and leaves the table in place if that fails. In version 1.6.1 a table of a removed plugin comes back as “Possibly unused” or “Unknown”, never “Safe to remove”, so each drop is your decision. Leave tables without your site’s prefix alone unless you know what they are.

Cleanup Scanner → Orphan Data finds rows whose parent no longer exists, such as post meta of deleted posts, plus housekeeping data: revisions, auto-drafts, trashed posts, spam and expired transients. Click Run Orphan Scan, then use Clean Up Selected (Safe to remove) for exact relationships or Remove Selected After Review, with DELETE typed, for the “Possibly unused” rest. Each row is checked again when it is deleted and saved to a backup file first, and Restore rows on the Cleanup screen puts rows back. Removing revisions ends the ability to roll those posts back, and the backups can contain personal data until you delete them.

Good to know and troubleshooting

• Results are a snapshot: quarantining acts on the label stored in the scan. After changing a theme, activating a plugin or publishing content, run a fresh scan first.
• A file you use is labelled “Possibly unused” or “Safe to remove”: the scanner could not see the reference (see the blind spots above). Quarantine a small batch first.
• A file you think is unused is labelled “In use”: open Why. Common causes are the same file name in another folder (names are also matched on their own), a theme or plugin file that mentions it, meta of a deleted or trashed post, or another size of the image in use.
• “WordPress filesystem move returned false.” (shown on screen or in Reports → Activity log): WordPress could not get file access it can use, or could not move the file. Check the ownership and permissions of wp-content and uploads.
• “Attachment #N was left in place”: one of its files is In use or Protected, is shared with another attachment, or could not be backed up or moved. Nothing was changed.
• Restore says a file already exists at the original location: something took the path, such as a re-upload. Move or rename it and restore again.
• Deleting the plugin: nothing is removed unless Delete all Cleanup Scanner data when the plugin is deleted is ticked in Settings; then quarantined files and backups go with it. Otherwise they stay, with no screen left to restore them, so restore what you need first.

For a record, export the scan from Reports → Scan history as CSV or JSON before you clean up, and the log of what was done from Reports → Activity log afterwards. The full documentation covers every reason code and orphan check.

Links

Plugin page: Media and Database Cleaner for WordPress. Settings reference: Media and Database Cleaner documentation. More tools: Browse all plugins.