How to Clean Up the WordPress Media Library Without Breaking Pages
Years of uploads, three thumbnail sets each, and half of them attached to nothing. Here is how to reclaim the space without deleting the hero image on your homepage.
On this page
To clean up the WordPress media library safely, treat it like a demolition job: survey first, mark what goes, move it out of the way, wait to see if anything collapses, then haul it off. The tool matters less than the order. Scan for unused files, review the list with sizes shown, trash to a recycle bin rather than deleting, give it a week, then delete for good. Here is each step and the traps in between.
Why the library gets so big
WordPress never removes an upload on its own. Replace a hero image and the old one stays. Delete a post and its images stay. Retire a product and its gallery stays.
On top of that, every image you upload is resized into several versions: thumbnail, medium, large, and whatever sizes your theme and plugins register. Ten registered sizes means eleven files per upload. A library of 3,000 images is easily 30,000 files and several gigabytes.
So the bloat has two sources: files nothing references, and sizes nothing uses. Clean the first, then fix the second.
What “unused” actually means
A file is unused when nothing on the site refers to it. That is a stronger test than WordPress’s own “unattached” column, which only records which post a file was uploaded from. An image uploaded in one post and placed in another shows as attached to the first; an image uploaded through the library and used everywhere shows as unattached.
A proper scan checks references in:
- Post and page content, including image blocks, galleries and HTML
- Featured images and post metadata
- Widgets, menus and customizer settings
- Theme options and page builder data, which often store image IDs or URLs in serialized form
- Site icon, logo and background settings
- WooCommerce product galleries and variation images
Anything referenced in any of these is in use. Anything referenced nowhere is a candidate, not a certainty.
What a scanner cannot see
Be honest about the limits so you set up the safety net properly. A scan can miss:
- Images referenced in custom CSS as backgrounds
- Images used in email templates or external services pointing at your uploads
- Files referenced by custom code or in option values the scanner does not know
- Images hotlinked by other sites, which is not your problem but will produce complaints
This is why the recycle bin step exists. DevDome Media Cleaner finds unused and orphaned media, shows file sizes so you can prioritise, trashes selected files to a Recycle Bin, and restores or permanently deletes them after review. Scanning, cleanup and restore are free and need no account. We make it, so weigh that; whichever tool you use, insist on a preview and a reversible trash step.
The safe process, step by step
1. Back up. A full backup, or at least the uploads folder and the database. Cleanup is reversible with a recycle bin; a backup makes it reversible even if the bin fails.
2. Scan. Run the unused-media scan. On a large library this takes a while and may run in batches. Let it finish.
3. Review, largest first. Sort by size. The top fifty files usually account for a large share of the space. Spot-check a few: open the file, search the site for its filename, confirm nothing uses it.
4. Trash in batches. Move a batch to the recycle bin. Do not permanently delete yet.
5. Wait and watch. Browse the key pages: homepage, top posts, product pages, checkout. Check for broken images. Give it a week if the site is busy. If something broke, restore that file from the bin.
6. Delete permanently. Once a batch has sat in the bin without incident, delete it for good and reclaim the space. Repeat with the next batch.
Fix the source of the bloat
Cleanup once is good. Not needing it again is better.
Prune registered image sizes. Check which sizes your theme actually outputs. Plugins often register sizes for features you never use. Removing an unused size stops new uploads generating it.
Regenerate only what you need. If you removed sizes, a thumbnail regeneration run can drop the obsolete files, with the same recycle-bin caution.
Upload what you will use. A habit, not a tool: resize before uploading and avoid uploading five variants to pick one.
Schedule a check. A quarterly scan keeps the library from drifting back. Add it to your maintenance checklist next to broken-link checks and plugin cleanup.
Page builders and the references scanners miss
The most common bad delete comes from page builders. Elementor, Divi, Beaver Builder and similar store their layouts as serialized data in post meta, and images inside that data are referenced by ID or URL in a format each builder defines. A scanner that only reads post content sees none of it and reports every builder image as unused. Before trusting a scan on a builder site, check that the tool lists your builder as supported, then test it on one page you know well: trash the images that page uses, view the page, and see whether they broke. If they did, restore and treat every “unused” result from that builder as unverified until you have checked it by hand. Theme options and customizer settings work the same way: logos, backgrounds and section images are stored outside post content and need explicit support.
When not to bother
If your uploads folder is a few hundred megabytes, the risk of a bad delete outweighs the storage you would save. Cleanup is worth it when backups are slow, migrations time out, the library screen crawls, or the host is charging you for storage. In those cases the process above gets the space back without the panic of a missing homepage image.
Disclosure: DevDome publishes this blog and makes the products it mentions. We describe what they do rather than promise results.
Key takeaways
- WordPress never deletes an upload on its own, and every image carries several generated sizes, so libraries grow much faster than content.
- Unused means the file is referenced nowhere: not in post content, not as a featured image, not in widgets, options, page builder data or theme settings.
- No scanner can see every reference, so the safe process is scan, review, trash to a recycle bin, wait, then delete.
- Take a backup first and clean in batches, largest files first, so a mistake is small and reversible.
- After cleanup, fix the source: image sizes you do not need and uploads that never get used.
Sources
- WordPress.org: Media Library screen : how the library works and what attached means
- WordPress Developer Resources: add_image_size() : why each upload produces several files
- WordPress Developer Resources: wp_delete_attachment() : what deleting an attachment removes
Links last checked October 17, 2026.
Frequently asked questions
Why does WordPress say an image is unattached when I am using it?
Attachment in WordPress only records which post the file was uploaded from. An image placed in a different post, a widget or a page builder block is still in use even if it shows as unattached. Never delete based on the attached column alone.
Can deleting unused images break my site?
Yes, if the scan missed a reference. Common misses are images referenced in theme options, page builder settings, CSS backgrounds, email templates and external sites hotlinking your files. A recycle bin with a waiting period catches most of these safely.
How much space will I get back?
It depends entirely on the site. Blogs that replaced images over years and shops with retired products often recover a large share of the uploads folder. A scan reports file sizes, so you know before deleting anything.
Will cleanup make my site faster?
Not directly. Visitors only load the images on the page they view. Cleanup speeds up backups, migrations and the media library screen itself, and reduces hosting storage. For page speed, optimise the images that are actually used.