How to Clean Up Your WordPress Media Library

Every WordPress site accumulates media library clutter. You delete a post but its images stay behind. You switch themes and the old thumbnail sizes become dead weight. You migrate from one host to another and stale URLs get baked into your post content. A proper WordPress media library cleanup is something most site owners know they need but never get around to — because doing it manually is tedious and risky.

StaticQ Media includes three scanners that handle the three types of mess: metadata and file integrity issues, stale image URLs in your post content, and orphan files that aren’t referenced by anything. Here’s how to use all three.

---

The Three Types of Media Library Mess

Before jumping into the steps, it helps to understand what goes wrong:

1. Metadata and file issues. WordPress tracks each image in two places: the database (attachment post + metadata) and the filesystem (the actual files). These can drift apart. A thumbnail size gets removed from your theme but the files remain on disk. Metadata says a WebP variant exists but the file was deleted. The database says the image was uploaded to R2 but the cloud copy is missing. The Media Library Scanner catches all of this.

2. Stale URLs in post content. When you write a post in WordPress, image URLs are hardcoded into the post body as HTML. If your domain changes, your CDN changes, or you delete and re-upload an image, those URLs go stale. They don’t update automatically. The Post Content Scanner finds them.

3. Orphan files. Files sitting in your wp-content/uploads/ directory that aren’t attached to any WordPress media library entry. They got there from a deleted plugin, a failed import, a manual FTP upload, or a theme that wrote files directly. Orphan Detection finds them.

---

Step 1: Run the Media Library Scanner

Go to StaticQ > Media Manager and click Scan Media Library.

The scanner compares every registered attachment against your current WordPress configuration. For each image, it checks:

• Do all the expected thumbnail sizes exist on disk?
• Are the file permissions correct?
• Does the metadata match what’s actually on the filesystem?
• If WebP conversion is enabled, do WebP variants exist?
• If cloud offloading is enabled, are the R2 copies present?

This runs in batches via AJAX — it won’t time out on large libraries. When it finishes, you’ll see a summary of what it found.

Step 2: Fix All

If the scanner found issues, click Fix All. This queues repair tasks through WordPress cron:

• Missing thumbnail sizes are regenerated
• Missing WebP variants are created
• Files that should be on R2 but aren’t are uploaded
• Metadata is corrected to match the actual filesystem state

The queue processes in controlled batches — no CPU spikes, no timeouts. You can monitor progress in the Media Manager.

---

Step 3: Run the Post Content Scanner

Next, go to the Post Content Scanner section and click Scan Post Content.

This scanner reads through every post, page, and custom post type in your database. For each <img> tag it finds, it checks:

• Does the URL point to a valid attachment in your media library?
• Is the URL using your current domain, or does it reference an old domain?
• Is the image size in the URL still a registered size, or is it stale?
• Does the referenced file actually exist?

When it finishes, you’ll see a list of posts with problematic image URLs, categorized by issue type.

Step 4: Fix Stale URLs

Review the results. The scanner categorizes issues by type — wrong domain, stale image sizes, deleted attachments, and broken URLs. For issues it can fix automatically (wrong domain, stale sizes), click Fix All to rewrite the URLs in your post content.

For deleted attachments and broken URLs, you’ll need to handle those manually — re-upload the missing image or update the post. The scanner tells you exactly which posts are affected so you know where to look.

---

Step 5: Run Orphan Detection

Now for the files that shouldn’t be there at all. Go to the Orphan Detection section and click Scan for Orphans.

This scanner walks your wp-content/uploads/ directory and cross-references every file against the WordPress media library database. Any file that isn’t tracked by an attachment entry is flagged as an orphan. These are files that:

• Were left behind when a post or attachment was deleted
• Were created by a plugin that’s since been removed
• Were uploaded via FTP or file manager and never registered in WordPress
• Are leftover thumbnails from a theme you no longer use

Step 6: Review, Quarantine, Test, Purge

Orphan Detection is deliberately cautious. It doesn’t delete anything immediately. The workflow is:

1. Review the list of detected orphans. Browse the files to make sure nothing important was flagged.
2. Quarantine the orphans you want to remove. This moves them to a quarantine directory — they’re off the live path but still recoverable.
3. Test your site. Browse around, check key pages, make sure nothing broke.
4. Purge the quarantine once you’re confident. This permanently deletes the files.

This staged approach means you can always recover if the scanner flagged something it shouldn’t have. No data is lost until you explicitly purge.

---

How Much Space Can You Reclaim?

It depends on the age and history of your site, but the numbers can be surprising:

• A 3-year-old blog with theme changes and plugin experiments often has 20-40% orphan files by volume
• Sites migrated between hosts frequently have dozens of posts with stale image URLs
• Libraries with changed thumbnail sizes can have hundreds of unused resize files per image

One user on a 5,000-image WooCommerce site reclaimed over 8 GB of disk space from orphan files alone — thumbnails from three previous themes, leftover files from a gallery plugin, and images from products deleted years ago.

Even if you’re not low on disk space, cleaning up your media library makes backups smaller, migrations faster, and your content more reliable.

---

A Cleaner Library in 15 Minutes

The entire process — all three scanners, fixing issues, quarantining orphans — takes about 15 minutes for a typical site. Large libraries (10,000+ images) will take longer for the scans to complete, but the queue-based processing means it won’t bog down your server.

The result is a media library where every file is accounted for, every URL in your posts points to a real image, and nothing is wasting disk space. And because StaticQ Media is completely free — no Pro tier, no credit limits — you can run this cleanup on every site you manage.

Get StaticQ Media — Free on WordPress.org →