Delete unused images in WordPress: attachments, media, unattached images, 404, orphaned

!! Before anything: make sure you made a backup!

Remove unused images attachments (orphaned images that are not attached to any WordPress post, page or custom post)

When you delete your posts, attachments from them don’t get deleted automatically. They keep staying in the WordPress Media Library and on your web server eating disk space and messing things up.

The following function will delete them permanently. Both — from Media Library and from wp-content/uploads folder too.

Be careful with what you are doing. For example, in one of the projects we added images and descriptions on tags archive pages for SEO purposes and these images as you understand are not attached to any post, however that doesn’t mean we want to get rid of them.

If you’ve thoroughly thought this out and you are  sure you want to get rid of this orphaned media, here you go:

Delete all attachments related to a specific custom post type

This function is useful when you need to delete all images that are attached to a specified CPT.  For example, you used to have CPT on the side, and then deleted it or migrated leaving it behind.

Mind changing “card” to your custom post type name.

This will delete both — an attachment from WordPress, and an actual file from your web server.

Clean up WordPress Media Library: delete all attachments whose files are no longer present on a web server and give a 404 error (blank thumbnails in Media Library)

Is your Media Library populated with images that are not displayed? When you click them it says the image does not exist anymore and gives you 404 page?

This is a broken link issue. There is no file for that attachment stored on a web server anymore so you are seeing these empty squares in Media Library as ghosts of previously existing images.

You can delete images from WordPress Media Library with this function — it will clean up your Media Library from non-existent images by deleting all WordPress attachments whose files that no longer present on a web server.

Caution: resource greedy!

*Mind that if you have a link to such file somewhere in posts it will stay there and still give 404 to users. To explore this issue and find such broken links in posts I use Screaming Frog.

You are always making a backup before something like that. Right?

Reverse: How to find and delete unused images WordPress Uploads directory

Note: This part is not for attachments but for actual files, in your Uploads directory — reverse check!

If your website is more than a few months old you know how surprisingly large your wp-content/uploads can become one day. You don’t know where all that stuff comes from and where it goes but it just occupies all free space on your web server.

Here is how to define useless media correctly and get rid of it. Just watch out for what you are doing as delete means delete.

Case 1: all images on your site are stored as WP attachments

Good media: all WordPress attachments

Bad media: anything stored in uploads directory that is not WP attachment

This function will free up disk space on your hosting account. It will scan your wp-content/uploads directory (recursively) and check every found file whether it is WP attachment or not.

All files that are not WP attachments will be deleted. If you got a rather large uploads folder (say 5 GB) you might want to split the process into parts by folders.  I’ve got 1 GB checked and cleaned in 15 seconds (only 300 MB left!).

This is how we find and delete images which are not attachments.

But what if your images are not stored as WP attachments at all but are still used on your website?

Case 2: images on your site are uploaded through custom fields and are not stored as WP attachments

Good media: all images saved in specified custom fields

Bad media: anything else in uploads directory

Step 1: Define all good images

First, we need to get the combined list of all “good” images that are used on the website, so later we can delete all files that are not used.  

I’ll show one of the cases as an example. It’s an online bookstore. We’ve managed to get rid of 32 thousand of useless files and free up to 75% of disk space on a web server. 

Before: 42096 images 4767 MB

After: 9202 images 1251 MB

Cleaned 32894 images and saved 3516 MB disk space

Here we’ve got 3 post types: posts (used for books), book author and booklist. Image for every post type is stored in a separate custom field (book cover, author’s pic and book list image). We’ll obtain the list of images used for each CPT and combine them together to get a full list of good images. These are the images that we will preserve.

Step 2: Delete images not used by WordPress installation

So we’ve got the complete list of good images that are used on the website in variable $all_good_pictures. Now we’ll go through the wp-content/uploads directory and check every file whether it’s on the the list or not. If it’s not listed we’ll just delete it.

Okay, but EXACTLY what do you do with the code?

I was hesitant about adding this paragraph, but people keep asking me here, on GitHub, on Twitter, and via email, and everywhere — so:

If you don’t know what to do with these snippets, you added them to your functions.php nothing happened, and you don’t know WHY — my opinion: you should read about WP actions and hooks first, at the very least this short article.

In 2 words: all the snippets above are functions. (And yes, you need to place the needed one in functions.php of your child theme or via code snippet plugin if you use one.)
But those are functions.

You need to connect the needed function to the action to fire it.

For example, after_setup_theme action –> then to fire it you’ll use: add_action('after_setup_theme', 'function_name_here'); 
+ it would be very nice to check that the action you hooked to, runs only once.

Seriously, I would recommend getting acquainted with WP Actions and Hooks concept before all this. Or make a backup at least 🙂

Wrap up

Here is how we can get our WordPress install clean and well-organized, reduce data amount and CPU load and even move to a cheaper hosting plan as we won’t store gigabytes of trash anymore.

And just in case, you’ve made a backup, right? 🙂