Media Cleaner is a very advanced tool and should be used by someone who understands the mechanics of WordPress very well. This is not a one-click cleanup kind of tool, and cannot be. Also, cleaning the database of temporary entries or old drafts is easy, but files always are potentially in use. Media Cleaner is a tool in your hand. Make sure you are in control of it.
Media Cleaner offers more features than described here. Check out the latest documentation and feel free to join our Discord community!
Absolutely backup your site (the database and the /uploads directory) before doing this. I recommend you to use your hosting service backup system if they have any, a staging website if it’s available (WPEngine has one) or the very well-made BlogVault service.
The Dashboard
The Media Cleaner Dashboard is found under Media > Cleaner. This is where the magic happens: you pick a scan, you run it, you review what came back, and only then do you delete anything.
The four tabs under the toolbar are worth knowing straight away. Issues is what the last scan flagged. Ignored is what you told the plugin to leave alone forever. Trash holds what you deleted but can still restore. References is the opposite of Issues: every media reference the scan actually found in your content. When you are not sure why something was flagged, References is often where the answer is.
The four scans
The dropdown in the toolbar picks what kind of scan you are about to run. They do genuinely different things, so this choice matters more than any setting.
- Clean Library goes through every entry in your Media Library and checks whether your content uses it. This is the one to start with.
- Clean Uploads Folder (Pro) walks the /uploads directory itself and checks whether each file is registered in the Media Library, or used directly by your content. This is how you find the leftovers that the Library does not even know about.
- Clean Duplicates (BETA) (Pro) finds files whose contents are identical. Handy after years of re-uploading the same logo.
- Optimize Thumbnails (Pro) works out which thumbnails your site is actually supposed to have, lists the thumbnail files you really have, and matches the two so the unneeded sizes surface. It needs Thumbnails Only enabled to do its job, and the dashboard will warn you if it is not.
How to use it
Here is how you should use the plugin, without going into the details of what the scan is really doing and how. Again, remember that you must prepare a backup before doing all this.
Run the scan
Click Scan and then enjoy a coffee. The plugin works through its steps and shows you which one it is on, so you can see it is alive on a big library. Once it has finished, the results replace whatever was there before.
Check the results carefully
Watch out for the false-positive entries. For example, images used by the theme directly, such as logos, headers, etc. Look for them, and if they are part of those results, select them and click Ignore. Then, they will never be deleted by the plugin.
With the Clean Library scan, you will get a certain number of files between parenthesis, for example: “myfile.jpg” (+ 10 files). This is because there is an original file, and all its related thumbnails. If it’s not clear (or new) for you, please check my article about WordPress Image Sizes. With this scan, all the thumbnails are considered as used if any of them (or the original file) is used.
Delete or Ignore entries
You can search (= filter) through them. If you click Delete All after a search, only the results of this search will be deleted. You can also delete the entries one by one or by selecting a few of them. If there aren’t enough entries listed on each page for you, you can change that with the per-page selector at the bottom of the table. Remember that the files are being moved to the internal trash of the plugin, so they are still taking space in your install.
There is also an Export Results button in the toolbar, which is a good habit before a big deletion: you keep a record of exactly what was flagged, outside of WordPress.
Test your website
Browse your website thoroughly. If it’s a rather small website, you can simply visit every page manually. You can also run a Broken Links detector. Or… time will tell?
If some files are missing, look for those entries in the Trash tab of the Cleaner Dashboard, select them, and click Restore.
Empty the trash
Everything has been fine for a while? Click on Empty trash. The entries will be permanently deleted. Congratulations!
Different types of issues
- Not found in content. The media entry (or file) has not been found in the content of your website.
- No attached file. The media entry has no attached files. This media entry is broken.
- Not in Library. The file doesn’t belong to any entry in your Media Library. It’s probably an orphaned file, such as a thumbnail used by a previous theme.
- Orphan Retina or WebP. File which doesn’t have a master anymore. You can delete those your eyes closed.
Now that you know the process of Media Cleaner, let’s have a look at the settings.
The Settings
The settings are found under Meow Apps > Media Cleaner. By default, they are already good for most usage. Each kind of scan has its own tab, with the settings that apply to it.
Clean Library Scan
Media Cleaner used to be much more complicated, with many options. It has been simplified over the years, as users simply want to scan the content as a whole. But keep in mind that Media Cleaner looks at everything, everywhere, and even knows how your plugins are handling your data.
Content. The scan will analyze your content (posts, pages, other post types, metadata, widgets) and extract all the references to your files. Page builders are handled in the Pro version, through the parsers described below.
Images Only. If you only want to check your images, enable this. Nothing else will be scanned.
Attached Images. If a media entry is attached to a post (the Uploaded To field in the Media Library), it will be considered as being used. This is a safety net rather than a truth: plenty of attached images are not actually displayed anywhere. Turn it on if you would rather miss some junk than risk a false positive.
Clean Uploads Folder Scan
This is a Pro feature. The settings are similar, but they apply to the files on disk rather than to the Media Library entries.
Library. Your files will be matched against your Media Library. This is the best way to clean your install: if only this option is selected, then all the files which aren’t part of a media entry will be detected as unused.
Content. This will check if a specific file is used by your content directly. I insist on directly, that means by using its path. Often, images are used by the content through their Media ID, and then, when the page is generated, the actual paths are written.
Filters
Those filters will be applied during the scan.
Keep in mind that you can also search through the results of your scan using the search function in the Cleaner Dashboard. For example, you can type “/2020” in the search and results will be filtered by that directory. So you might not need those filters, they are for advanced users.
Before the filters are applied, the scan will need to go through all the directories and files first (one reason is that, even if you filter out a directory, some files or subdirectories might match positively your filters). Therefore, using filters will not make the scan faster.
Directories Filter and Files Filter can restrict the scanning to specific folders and/or files depending on a regular expression (expressed between two slashes). If you don’t know how to write a regular expression, it might be interesting for you to learn. There are many tutorials online, and then you can test them on websites such as Regex101. Here are a few examples:
- Directories Filter: /^$/ (only scan the root of your /uploads directory)
- Directories Filter: /^2018/ (scan only the files from 2018)
- Directories Filter: /^[0-9]{4}/02/ (scan only the files in the February directories)
- Directories Filter: /^((?!wp-slimstat|woocommerce-pdf-invoices|wpo_wcpdf|arprice|mk_assets|fvm).)*$/ (avoid scanning specific directories)
- Files Filter: /400×400.jpg/ (scan only the files of resolution 400×400)
- Files Filter: /.jpg|.png/ (scan only the png and jpg files)
Thumbnails Only. Will only scan your thumbnails and avoid the original (full-size) images. With WordPress, those filenames contain the resolution. This could also have been done with a regular expression but is to make life easier for most users.
Parsers
This tab is the answer to the most common complaint about Media Cleaner, and it deserves a minute of your attention.
Most plugins and themes store media references the way WordPress intends, and Media Cleaner reads those naturally, with no help needed. Some page builders and gallery plugins do not: they invent their own storage format, and a scanner that does not speak that format sees an unused image where there is a perfectly visible one.
Parsers are the small pieces of code that teach Media Cleaner those formats. This tab lists the ones that are active on your site. In the screenshot above, Divi, Bricks Builder and Foo Gallery were detected and are handled.
Check this tab before your first cleanup. If you use a builder or a gallery plugin that is not listed, treat every result with real suspicion, because that is precisely where false positives come from.
Advanced
Most of these are self-explanatory, or exist to tune the speed of the scan against your server’s patience. The buffers on the right control how many entries, posts or files are handled per batch: raise them on a strong server, lower them if scans time out.
Two are worth calling out. Skip Trash disables the trash and the restore feature entirely, which I would not recommend to anyone who has not done this a dozen times. MCP is the one that opens the door to AI agents, and it has its own section below.
Logs & Debug
Logs. This option will create a file (which is reset at every scan) containing all the files detected in your install in the first section, then the result of the scan for every media or file in a second section.
Recommended Procedures
Having a headache already? Here are the typical procedures that you should be aware of.
Standard Check (Clean Library)
This is the most common analysis, and the one to run first. Select Clean Library, keep Content checked, and scan. The default settings are already fine.
Meticulous Check (Clean Uploads Folder)
This is a Pro feature. After the Standard Check, this is the most recommended scan. Select Clean Uploads Folder and check Library. This one will carefully check if your files are indeed registered under media entries. Normally, they all are! But as you will soon realize, it’s really easy for WordPress to become a mess, and having gigabytes of unused files is not very surprising (which could be also WebP and Retina leftovers).
Broken Media Check
Do you have a lot of broken media entries? This could be useful for you. It will check the broken media entries, by basically looking if the related files exist or not. For this special check, select Clean Library and uncheck everything under Scanning. What remains flagged are the entries whose files are simply gone.
Optimize Thumbnails
You feel like WordPress is creating a huge amount of thumbnails, while only few of them seem to be in use. You might be right, practically. But technically, this is wrong: all the thumbnails registered in the metadata might currently be in use or… at a later point of time. Even if you delete them, since they are part of the metadata, they will be regenerated.
The Optimize Thumbnails scan takes care of the comparison for you: it works out the thumbnails your site is supposed to have, lists the ones actually sitting on disk, and matches them so the pointless sizes surface. Enable Thumbnails Only before running it, otherwise the scan tells you it cannot do its job.
The real fix, though, is upstream: decide which image sizes your site genuinely needs. If you use WooCommerce but never use WooCommerce galleries, you can disable the corresponding registered size. Media Cleaner does not list image sizes, but Perfect Images does it in its free version, and it can regenerate your thumbnails afterwards to refresh all your metadata. Here is how: Perfect Images Tutorial. Keep in mind that this is not about cleaning, it’s about overriding your theme and plugin behavior. Once that is done, run the Meticulous Check and the corresponding files will be erased.
Clean Duplicates
This is a Pro feature, and still in beta. It finds files whose contents are identical, which happens naturally after a few years of re-uploading the same logo, the same header, the same product photo. Review these ones especially carefully: two identical files can both be legitimately referenced from different places, and deleting one will break whatever pointed at it.
Automation: AI Agents (MCP)
This is the newest way to use Media Cleaner, and honestly the one I reach for now.
If you also run AI Engine, Media Cleaner registers its own tools with it, and your WordPress becomes an MCP server. An AI agent, such as Claude or Claude Code, can then connect to your site and run the whole procedure with you. The MCP option lives in the Advanced tab shown earlier, switched off by default.
Why bother, when the buttons are right there? Because the thing that makes Media Cleaner dangerous is exactly the thing an agent happens to be good at: patience. A scan hands you a list of suspicions, and someone has to look at each one and think about it. That work is tedious, so humans skip it, click Delete All, and then discover three weeks later that the theme’s logo is gone. An agent does not get bored on entry 900.
The tools were designed around that idea. There are twelve of them, and their shape matters more than their names:
- wpmc_get_capabilities reports what Media Cleaner can and cannot see on this site: which parsers are active, which of your installed builders or plugins are not supported, and where the blind spots are. Agents are told to call it first, so they know upfront which media a scan must not be trusted about.
- wpmc_scan_start, wpmc_scan_step, wpmc_scan_publish and wpmc_scan_cancel run a staged scan, in small bounded batches so your server is never hammered. Nothing replaces your existing results until every phase has finished, so an agent cannot act on half a scan.
- wpmc_get_status and wpmc_get_issues give the current state and the list of flagged media. The tool description says it out loud: these are suspicions, not proof.
- wpmc_explain_issue is the interesting one. It explains why a given file was flagged, which is what turns “the scan says it is unused” into something you can actually judge.
- wpmc_ignore, wpmc_trash, wpmc_recover and wpmc_delete_permanently act on the results, with the plugin’s trash still sitting in the middle as it always has. Permanent deletion requires an explicit confirmation.
In practice, a session looks like asking for this: “Scan the media library. Before deleting anything, check each flagged file against my theme and my page builder, and tell me which ones you are not confident about.” The agent runs the scan in batches, explains the entries that matter, and hands back a much shorter list with reasons attached. You still make the call, but you make it on twenty files you actually read instead of four thousand you did not.
An agent is a careful assistant, not a safety net. It is better than you at reading four thousand rows, and worse than you at knowing what your site actually looks like. The backup rule at the top of this page applies every single time, agent or no agent.
Automation: WP-CLI
This is a Pro feature. It’s not possible to automate the process of cleaning from within WordPress. It would be way too dangerous, uncontrollable, and would also slow down your install at every visit. I actually advise you against scheduling automatic processes directly on WordPress. However, you can do this using WP-CLI, and that will not slow down your install as it will be executed in a different environment.
If you are the admin of your server or if your hosting services offer you SSH access and WP-CLI, you can run Media Cleaner from the command line. This also brings new possibilities like running a scan every once in a while, getting the results by e-mail, etc.
Basic Commands
To run the scanning based on your current settings:
wp media-cleaner scanYou can override the settings it runs with by specifying the method (media or filesystem) and the options (check-content, uncheck-content, check-media, uncheck-media). For example, for running the Standard Check, you would use:
wp media-cleaner scan media check-contentAt the end of the scan, the list of issues will be displayed. If you need to have it displayed again (or to count the number of lines), you can use:
wp media-cleaner issuesEach result will look like this in the listing:
– [#407] Media 268: 2025/09/my-file.png (+ 4 files) (NO_CONTENT)
The first ID is the one used by Media Cleaner. So above, if you need to delete or restore exactly this entry, you will need to use 407.
Advanced Commands
If you want to go further and automate all this, at this point, you must prepare a backup. Then you can run the deletion process, and the issues will be sent to the trash. You can specify a certain issue ID to only delete that one.
wp media-cleaner delete
wp media-cleaner delete 407If you want to list the items in the trash, you can use:
wp media-cleaner trashIf you realize there are items you do not want to delete, you can recover them:
wp media-cleaner recover
wp media-cleaner recover 407And finally, if you would like to empty the trash, you can also do that.
wp media-cleaner emptyAdvanced Shell Scripting
The WP-CLI should be used by administrators, so hopefully they are very fluent with piping and shell commands such as grep, sed and all the others. Thanks to all this, you can perform searches on the issues (or the trashed items), restore a selection of them, etc.
For now, I will share one useful command with you:
wp media-cleaner issues | grep tokyo | sed -n 's/- [#([0-9]*)].*/1/p'This command above will list all the issues which contain tokyo (in the filename), and will only display the Media Cleaner IDs of those issues.