How to Delete Unused Images in WordPress

No plugin can tell you for certain which images are unused — so delete with a backup, a trash and a waiting period. Page builders, theme options, widgets and CSS store image references in places scanners miss, and a wrong deletion produces broken images that nobody notices for months. Before deleting anything, check whether your actual problem is disk space; removing unused sizes often frees more with far less risk.

Why "unattached" is not "unused"

The media library's Unattached filter (Media → Library) shows images with no parent post. That parent is set when an image is uploaded from inside a post's editor, or attached manually with Attach in list view. An image is unattached but in use when it was:

• uploaded in Media → Add New, then inserted into posts;
• set as a site logo, header or background in the Customiser;
• used in a widget, menu or block template part;
• placed by a page builder, which stores layouts as JSON or shortcodes;
• referenced in custom CSS or theme options.

And an attached image can be unused: the post it was uploaded to may have dropped it long ago. The filter is a starting point, not a verdict.

How cleanup plugins scan

Cleanup plugins search the database for each image's URL, ID and filename — post content, post meta, options, widgets — and flag images with no match. Their blind spots:

• references in serialised or encoded builder data the plugin does not parse;
• images referenced by ID through a custom field it does not know;
• CSS files and theme files on disk;
• external sites and emails that hotlink your images.

The better ones move flagged files to a trash or quarantine first and let you restore them. Prefer that over immediate deletion, whichever plugin you use.

A safe procedure

1. Back up the database and wp-content/uploads — see WordPress backup plugins.

2. Enable the media trash in wp-config.php, so deletions are reversible:

   Copy

   define( 'MEDIA_TRASH', true );
   

3. Work on staging first if the site uses a page builder — see how to create a staging site.

4. Scan, then review the flagged list by hand; skip logos, icons and anything with a generic name.

5. Trash, do not delete. Leave the trash for a few weeks while you browse the site and watch for broken images.

6. Empty the trash only after that period.

Broken images after a cleanup look exactly like the problems in WordPress images not showing; check the backup before debugging anything else.

Check the obvious places by hand

Before trusting any scan, look at the places scanners miss most often:

Ten minutes here prevents most of the damage a cleanup can do. Anything found in these places goes on a keep list before you review the scan results.

Files on disk that are not in the library

The opposite problem: files in wp-content/uploads with no media library entry, left behind by failed uploads, removed plugins or migrations. They are invisible in the dashboard and safe to remove only when nothing links to them. Compare the folder against the attachment list — wp post list --post_type=attachment --field=guid from WP-CLI against find wp-content/uploads -type f — or use a plugin that reports orphaned files, and archive rather than delete.

Free space without deleting images

On most sites, uploads are large because of generated sizes and oversized originals, not because of unused images:

• Unused sizes. A previous theme may have registered six sizes nothing uses; regenerating with deletion removes them, as described in regenerating thumbnails.
• Camera originals. Since WordPress 5.3, uploads over 2560 pixels keep the original next to the -scaled copy. Capping uploads is covered in how to resize images.
• Uncompressed files. Compressing the whole library usually saves more than any cleanup. An optimizer that resizes oversized originals and compresses every size in bulk, such as Imagify, can cut the library substantially. Its originals backup lives in wp-content/uploads/backup/, so the folder only shrinks once you have checked the results and removed that backup.

Disk usage is also worth checking against what the host counts: some include backups and logs in the quota, so a full disk may not be the uploads folder at all.

Organising uploads so the next cleanup is easier is in the WordPress media library.

Common mistakes

• Treating Unattached as a delete list.
• Deleting without MEDIA_TRASH, which makes every mistake permanent.
• Trusting a scan on a page-builder site without testing on staging.
• Deleting images still linked from other sites or emails, which then show broken.
• Cleaning images when the real weight is image sizes and originals.

Verify

1. Before and after, record the size of wp-content/uploads with du -sh or the host's file manager.
2. Crawl the site for broken images, or check key templates — home, archives, products, landing pages — by hand.
3. Check the server's 404 log for /wp-content/uploads/ requests in the weeks after cleanup.