Tutorial & Debugging

Media Cleaner is a very advanced tool and I could write many articles about how to use it depending on every WordPress install. Remember to backup your install (database and /uploads directory) before using this plugin.

Basic Process

Pick your options, start the scan, wait (that can take time depending on your install – if it stops suddenly, please check your PHP Error Logs). Check the files which are detected – are they actually not in use? Are you sure? Delete them with the plugin. They will go in the plugin’s trash and the database entry for the Media will be kept. Use your website for a while. Everything works? Trash them permanently by going in the Trash in the Media Cleaner’s dashboard. Many broken files? Restore them using the dashboard.

The process of checking the files is relatively intensive. Disabling all other plugins during the process is recommended.

Use Cases

I have one website on which I use my images in posts only (this one: Offbeat Japan). I set the Method on Media Library and the only options I check are Posts and Post Meta. Posts will check the content of my posts (and also pages, and other WordPress post types registered by your theme). Post Meta will check for usage in the related meta, which includes for examples the Post Thumbnail.

I have another website for which I only use my photos in galleries and/or as a Post Thumbnail (this website: Haikyo.org). I don’t need Posts in that case, but I use Post Meta and Galleries. This Galleries option check the usage of the media in the Gallery shortcode of WordPress (so we are not talking here about very specific gallery systems, especially those like NextGen who basically override all WP rules and are not natural to WP workflow).

Additional Use Cases with Pro

When my Media Library is clean, after the previous process, I switch to the Filesystem method. This will scan all the files in the /uploads and check if they are in use. For this, there are also many ways.

A good check is to select only the Media Library option with the Filesystem method. This will make sure that all the files in your /uploads directory are linked to a Media. Be careful, by only checking this, you don’t actually check if the files are used anywhere else. Maybe they are not in use, they are just registered in WordPress.

Another one is to check everything but not the Media Library. That’s useful if you uploaded files directly, or that your Media Library is broken for some reason.

Those are examples. Of course, there are many different ways of using this plugin. Make sure you understand how it works and what it does. Again, this is a dangerous tool.

Common Issues

First, I would like to say that getting the Pro version will not make everything better. If the free has an issue, the Pro will not fix it. It wouldn’t be fair for me to do that to my users. The Pro version adds interesting options, but it doesn’t mean it works better.

It suddenly… stops!

It happens mainly for two reasons:

  • The server is too slow, and the request couldn’t be finished in the time allowed by your server (PHP settings). In that case, have a look at the plugin settings, at the Advanced Settings. You can change those to slow down the process. Try lower values (except for the Delay which could/should be higher). You can also disable the other plugins during the process.
  • An error happened on the server. You need to have a look at your PHP Error Logs. That might help. Any error, even if it is coming from another plugin or issue will stop the plugin to work properly.

It detects… everything as used!

It means your images might have been used somewhere you didn’t suspect. Look at all your images and find one that you are sure is not used anywhere on your website. Click on it in the Media Library. On the right, there is a little widget called Media Cleaner.

Media Cleaner Usage

It will indicate to your something like: Seems to be used in a gallery, or Seems to be used in a post (and in that case, you will get a link to that post). Does this help you?

It detects… nothing as used!

Make sure your options are set right. Have a look at your PHP Error Logs. Is there any error? Is it related to the plugin?

Then you might be using a page builder that it is not supported by Media Cleaner. Are you using one?

If you are using WordPress very conventionally and think something is wrong, contact me. I will need to know an example of a Media detected as not in use, and I will need to know how is it used. That part is important. For example, edit the post where the image is indeed used, check for the HTML, find where the image is referenced (could be its URL, could be its ID). Give me this information so that I can replicate your issue.

Questions / FAQ

Please ask your questions in the comments below. Please check your PHP Error Logs before writing simply that it doesn’t work, it would be impossible to tell you why without it.


How to display more results?
Go see your Post list. There, you have a Screen Options at the very top, click on it. You can change the Number of items per page, this value is used by the plugin.
  • queeckee

    Hi Jordy. that would me a nice option to have. something like a stop button, to pause the scan and allow user to worh with part results. in many posts / images sceneriu the scan would take too much time, is there any temporary result list to load or something after timeout?. i am asking in advance, scan is still running πŸ™‚

    • queeckee

      WOW! i didnt except this. seems like wery well made.. i had accidentaly missclcked to leave te scan page, and result list is fantastic. even while in the half of scan. it found old diferent thiumbnail sizes as well. so i can only suggest this plugin for everyone! (dont forget to backup, and read notes twice, dont forget to activate media trash before you are happy to process delete! :))

  • 8 (ATE)

    I think our site is too large. It only gets to 9% and then it detects an error and just stops. The scan found 13,000 images. We were hoping this would work so we could purchase the PRO because we have thousands of images that need to be removed from our upload files (we’ve switched hosts 3 times in 2 years). I checked the error logs and don’t see anything as to why this is happening.

    • It seems very large indeed πŸ™‚ But I want to make the Media Cleaner works on big installs as well, which is why the plugin improved a lot recently to support this, even if it has to analyze those kind of installs slower. Best is to check the error in the Developer Tools of Google Chrome but if you don’t know how to do it exactly, can you contact me through the Contact / Support page and I will try to make it work πŸ™‚

  • Abdulrahman Nahhas

    I would ask to you also delete unused thumbnails? or just main images?

    I have a site since 2011 and we have a lot of articles. we change many themes and now I ned to clean the upload folder. when we delete the articles we dont delete the images. so I need to clean my upload folder I have a backup file with 10 GB. I dont know which images used or not. we have 20000 article.

    • We can’t delete the main images and keep the thumbnails, that would be a big mess πŸ™‚ However, it’s true I could add an option to delete the thumbnails, as right now the plugin is safe and keeps the main image + thumbnails in case any of those images is in use.

      However, if you switch between themes and re-generate the thumbnails, indeed you would have thumbnails with are not even part of your database anymore and therefore, pure garbage. The Pro version of Media Cleaner detects those in the Filesystem mode and you can delete them, did you try?

  • pbourhis

    My CPU Usage is 100% when running the scan and of course your plugin stop. I would like to know the right settings I will have to use on my poor shared server? Because it seems that the settings you show us here in your screenshot are high?

    • Hi, that’s a bit strange but if your server is slow and you have a big database then it can happen easily yes. Give it a bit of delay, like 2000ms, and with a lower Analysis Buffer, like 1 πŸ˜‰ Does it work better?

  • Sarah

    When I try to empty trash or delete an image, it says Analyzing and nothing ever happens. Anything I can do to fix this?

    • Actually there is an issue and it’s showing Analyzing while actually it’s Deleting. But it should happen anyway. Did you check your PHP Error Logs?

  • RobRab2000

    Hi, Thanks for a great plugin. Before I upgraded to pro, the plugin found 3700 files in my media library. After I installed the pro version it is finding over 180,000!! So I’m very happy indeed that I purchased the pro version (very reasonable price too).

    The issue I’m having though is that with so many files, I’m finding it very difficult to get through them all in one go. Is there any way to run this from the command line on the server so that wordpress isn’t getting in the way?

    Alternatively is there a way to get it to automatically retry when it gets an error. I find that every half hour or so it has a 504 error and stops. I can get it going again by hitting retry without refreshing the page. This makes it really difficult to leave it running over night. If it would auto retry then it should be fine.

    Thanks again πŸ™‚

    • RobRab2000

      oh dear, actually I have just realised that after getting to around 40% analysing and me deleting images along the way (around 42,000 images) it seems to have broken a lot of the the images on the site! I suspect it might be because I am using the cornerstone page builder and maybe it can’t see images in this?

      Is there anything I can do about this?

      • RobRab2000

        Hey, it turns out that the missing images were an issue with my DNS.. lol

        I will try the cleaner again πŸ™‚

        • Ah yes, it’s important to make sure all caches are reset every time (including CDN). So maybe that’s why πŸ˜‰ Happens often.

  • The Crystal Focus

    Hi Jordy,
    I’m back again and using the media cleaner pro because I inadvertently had retina create 11 versions of every image so I’m trying to prune my media library from 110,000 down to a more reasonable 1400 or so as it should be.
    I ran into issues with trying to move my site from localhost via MAMP (moved it local so that I could run WP/LR faster because I’m hashing almost 83,000 images in Lightroom Total Synchronization). The uploads folder had ballooned to over 18GB! In figuring out how to use media cleaner pro, I discovered the “wplr-tmp” folder – are those the hashes that Total Synch is creating? Because although I thought it was the retina creating all those versions that was causing my uploads folder to balloon to 18GB, it is actually that wplr-tmp folder that is now 17.4GB of that massive uploads folder! Do I need to keep all those temp files while WP/LR Total Sync is matching photos? Will Lightroom maintain its connections if those don’t go up to the server? Basically the problem seems to be that the restore is just timing out due to the size of that temp folder. Any suggestions?

    • Hi! The “wplr-tmp” is totally useless, it is temporary used to upload the photos, once they are uploaded and moved to WordPress Media Library they are removed from there. I am not sure why it happened, or maybe the Total Synchronization made this mess? It is actually a possibility and I will have a look. Meanwhile, you can delete this directory without thinking πŸ™‚

      • The Crystal Focus

        Thank you! This 17GB albatross has been waddling its way to and from the server for no reason. Hope you enjoyed the ride, “wplr-tmp”, cause you’re gonna take a final ride to the trash now. πŸ˜‰

  • nycmac.com

    Hi Jordy, images used by Slider Revolution and SiteOrigin Page Builder are marked as unused and deleted. It might be good to post a list of common plugins with known incompatibilities until they can be fixed.

    • Hello πŸ™‚ There are way too many plugins to do that, so I try to maintain rather a list of plugins with which I am compatible. Please contact me directly (https://meowapps.com/contact/) as I keep a list of the most used plugins by my user to make them compatible πŸ™‚

      • nycmac.com

        Thanks and you’re correct β€” I should have rephrased the suggestion to be about known *compatible* plugins.

I recommend you to use WPEngine or SiteGround. They are both excellent hosting services and work perfectly with all my plugins.