Find and delete unused WordPress media files
Published Updated 2 min read
A WordPress site that has run for a few years usually has a media library that no longer matches the site: images from posts that were later deleted, test uploads from campaigns that ended, files imported from a previous platform. Nothing removes them, and disk usage climbs until someone has to deal with it.
Scan-and-delete tools like Media Cleaner look through post content and flag attachments that nothing seems to reference. The trap is custom fields. ACF stores image selections as attachment IDs in post meta, so a scanner that only reads post_content marks every ACF image as unused. On a site using ACF for team photos, product galleries or testimonials, that is a quiet way to delete content that is live. A cleaner you build for your own site with an AI plugin builder can check the fields your site actually uses.
Deleting a post leaves its images behind
WordPress does not delete attachments when a post goes. The post moves to trash and disappears; every image uploaded to it stays in the library. Add years of publishing, staff turnover, theme changes and staging imports, and much of the library is connected to nothing live.
Nothing in the media grid tells you which. An unused image from 2022 looks exactly like the featured image on the homepage, and only a search of the database for references can tell them apart.
Three places a reference can hide
The plugin adds Media > Unused Media with a Scan button. A scan checks three places for each attachment:
- Post content across all post types, for attachment IDs in Gutenberg block markup and classic editor image HTML.
- Post meta for all posts and pages, including serialized arrays, which covers ACF image and gallery fields.
- Featured images, stored under the
_thumbnail_idmeta key.
Reviewing before anything is deleted
Anything with no reference in any of the three appears in a table with a thumbnail, file name, upload date and file size. Tick individual files or the whole page, and Delete Selected asks for confirmation before removing anything. Afterwards the page reports how many files went and how much disk space came back.
Deletion is permanent, so take a full backup first. Then delete in small batches until you trust what the scan is finding. On a site with thousands of posts the scan itself can take several minutes, and the page waits until it finishes.
Widgets and the customizer are blind spots
Widget content and theme customizer settings live in wp_options and can point at an image by URL rather than attachment ID. Custom tables created by other plugins sit outside the standard schema. The scan reads none of these, so an image used only there will show as unused.
If your site leans on widgets or customizer images, check those by hand before a bulk delete. Delete a small batch, look over the site, then carry on.
What you get
Included
- Scanning post content across all post types for embedded attachment references
- Scanning post meta including serialized ACF gallery field values for attachment IDs
- An admin screen listing unreferenced attachments with thumbnails, file names, dates, and sizes
- Bulk deletion with a confirmation step and a summary of files and disk space freed
Not included
- Images referenced in widget content or theme customizer settings stored in wp_options
- Images stored in custom database tables created by third-party plugins
- Resized crop files generated by WordPress, which are not tracked as separate attachments
- Recovering accidentally deleted attachments: deletion is permanent, so take a backup first
Media Cleaner does the things on the right. This build covers the part most sites use.
Build it in Steem
The button opens the builder with this guide's prompt filled in, so you can change anything before it runs. Nothing is built, and nothing is charged, until you send it.
Read the prompt (151 words)
Build a WordPress plugin that finds and displays unused media library attachments. Add an admin page under Media > Unused Media. Add a Scan button that queries the database for all attachment post IDs, then checks whether each ID appears in: the post_content of any post, page, or custom post type; any post meta value including serialized arrays, covering ACF image and gallery fields that store attachment IDs; or the _thumbnail_id post meta key used for featured images. After the scan, display unreferenced attachments in a table with columns for a small thumbnail, the file name, the upload date, and the file size in kilobytes. Add a checkbox on each row and a Select All checkbox in the header. Add a Delete Selected button below the table that shows a JavaScript confirmation dialog before deleting. After deletion, display a message with the count of deleted files and the total megabytes freed.
Steem