Description
Most cleanup plugins tell you an image is unused. This one tells you how sure it is, and why.
That difference matters, because the cost of being wrong is not symmetric. Leaving an unused image costs you a few kilobytes. Deleting a used one breaks your site — and you may not find out for weeks.
Version 1.1.0 adds an alt text audit with rule-based and optional AI suggestions — see below.
Read the full guide — why “unattached” is not the same as “unused”, the places a reference hides, and how to check by hand · Plugin page · Development on GitHub — report issues or contribute.
What it actually does
Scanners search every place an image can hide: featured images and post attachments, post content, Gutenberg blocks and synced patterns, full-site-editing templates, the Customizer, theme options, widgets, menus, Elementor, ACF, WooCommerce, and your theme’s PHP, CSS, and JavaScript files.
Then two independent judgements are made about every image:
- Confidence — how sure we are the image is unused
- Risk — how much damage deleting it would cause if we are wrong
These are never blended into one score. A site logo nobody references and a stray upload nobody references look identical to a confidence score, and demand opposite actions.
Alt text audit
A separate screen lists every image missing alt text (or carrying a weak one like “IMG_2034”), suggests a replacement built from the filename, title, or parent post, and applies it only when you say so — with undo. The suggestion is editable: apply it as-is or write your own words. Images can be marked decorative, a Dashboard card tracks your coverage, and wp janitorix alt stats reports coverage for scripting. Nothing here affects confidence, risk, or any deletion recommendation.
Optional AI suggestions
The alt text screen can also ask an AI model — but only if you enable it under Settings and add your own API key. One-click presets for Gemini, OpenAI, Groq, and OpenRouter fill in the endpoint and a working default model, so setup is “pick yours, paste the key” — and a test-connection button confirms it works before you spend anything. The plugin ships no key and makes no AI calls on its own. Each suggestion is reviewed in the textbox before anything is saved, exactly like a rule-based one, with rate-limit handling and cached answers so you never pay twice for the same image.
External services
AI suggestions are off by default. When you enable them and save a key, each image you ask about is sent — resized to at most 1024px — together with its filename and its parent post’s title, to the service at the base URL you configured. The plugin itself stores nothing externally; what the service does with that data is governed by its own terms, which you accept when you create your key. Providers differ — some train on API data, some do not — so read your chosen service before enabling. Examples (your own service’s terms apply, not these examples):
- OpenAI — Terms · Privacy
- Anthropic — Legal · Privacy
- Google Gemini — Terms · Privacy
- Groq — Terms · Privacy
- OpenRouter — Terms · Privacy
No other part of this plugin contacts any external service. Scans, suggestions, and reports all run on your own site.
What it refuses to do
- It will not recommend deleting anything if it could not search enough of your site. Below 70% coverage, it says so and recommends a rescan instead.
- It will not offer Trash for anything at Medium risk or above, no matter how confident it is.
- It will never delete your site logo, icon, or header — those are refused outright, not merely scored low.
- It will not touch an image uploaded in the last 24 hours, because you probably have plans for it.
- It never deletes anything in one step. Trash first, always, and only from the Trash can anything be permanently removed.
- It never contacts any external service on its own. The only network call the plugin can ever make is an AI suggestion you explicitly ask for, after enabling it with your own key.
Every number shows its work
Open any image and you can see which scanner found what, how strong each piece of evidence was, and exactly why the plugin reached its conclusion. A confidence score you cannot inspect is a number you have no reason to trust.
Honest about its limits
A perfect scan reports 97%, not 100%. Proving an image is used takes one piece of evidence; proving it is unused means proving the absence of evidence everywhere — and “everywhere” is not somewhere you can finish visiting. Theme frameworks store images in ways nobody can fully predict, and page builders can assemble URLs at render time.
The plugin reports the honest number rather than a comfortable one.
Screenshots
Installation
- Upload the plugin through Plugins > Add New, or upload the ZIP via Plugins > Add New > Upload.
- Activate it through the Plugins menu.
- Open the new Janitorix menu in your WordPress admin sidebar.
- Click Start the first scan on the Dashboard. Nothing is deleted until you decide to act on a recommendation, and nothing is ever removed permanently without first going through the Trash.
FAQ
-
Can it delete an image my site is using?
-
That is the failure mode the entire design exists to prevent, and it is why coverage floors, risk ceilings, and never-delete rules all sit between a scan and any action. But no scanner can see a URL assembled at runtime, or an image embedded in a newsletter you sent last year. Trash first, and check before emptying it.
-
Does it support my page builder?
-
Elementor is supported directly. For builders that are not — Divi, Bricks, Oxygen — a fallback scanner sweeps for image references it does not understand. It will not raise your confidence score, because it cannot prove it searched thoroughly. It can and does prevent deletions.
-
Why is my confidence score low?
-
Open the dashboard. If a scanner failed, it is named. If coverage is below 70%, it says so. The score is never lowered without a reason you can read.
-
Is anything deleted automatically?
-
No. Nothing is ever deleted without you clicking, and nothing is deleted in one step.
-
What happens when I uninstall it?
-
Every table and option the plugin created is removed. Your media is not touched.
-
How do I find unused images in WordPress?
-
The Media Library’s “Unattached” filter is not the answer — see below. Check post content, post meta (ACF fields, page builders, featured images), options (logo, Customizer, widgets), and theme files, by filename and by attachment ID. Or run a scan here: every image gets a confidence score with the evidence behind it.
-
Is it safe to delete unused media in WordPress?
-
Only after two conditions: the image is proven unused (not merely unattached), and deletion goes through Trash first so a mistake is reversible. This plugin enforces both — it refuses Trash for anything at Medium risk or above, and nothing is ever deleted in one step.
-
Why does my media library keep growing?
-
Every upload stays unless someone removes it, and WordPress generates several resized copies per upload. Unused originals plus their thumbnails accumulate silently. A periodic scan keeps it flat.
-
Does deleting images hurt SEO?
-
It can, in ways no database scan sees. An image can be unused on your site and still rank in Google Images or be hotlinked elsewhere — check Search Console, Performance, Images before a bulk delete. Deleted URLs return 404, which loses any signal they had; redirect if they mattered. Sitemaps list images too, and take time to regenerate. When in doubt, Trash and wait before emptying.
-
What is the difference between “unattached” and “unused”?
-
“Unattached” only means the image was not uploaded inside a post. It says nothing about whether anything references it — a logo, a Customizer image and most page-builder images are all “unattached” and all in use. Unused means no reference anywhere, which takes a real search to establish.
-
Does the AI feature send my images anywhere?
-
Only when you ask it to, image by image. Enabling AI and saving your own key sends nothing by itself. Each “Suggest with AI” click sends that one image (resized to at most 1024px), its filename and its parent post’s title to the service you configured — see “External services” above for exactly what goes where. Rule-based suggestions never leave your site.
-
Does alt text change on its own?
-
No. Nothing is applied until you click Save or Apply on that image, and every change keeps an undo. Marking decorative, editing the suggestion by hand, or dismissing an AI suggestion all work the same way — your call, reversible.
-
Is the alt text shown here the same as on the page?
-
Not always. This screen reads the alt text stored on the image itself; a theme or page builder may override it where the image is shown, so what a visitor actually hears can differ. Fix the stored text here first — that is the source everything else falls back to.
Reviews
Contributors & Developers
“Janitorix Media Audit” is open source software. The following people have contributed to this plugin.
Contributors
Translate “Janitorix Media Audit” into your language.
Interested in development?
Browse the code, check out the SVN repository, or subscribe to the development log by RSS.
Changelog
1.1.0
- New: alt text audit — a dedicated screen listing images with missing or weak alt text, with rule-based suggestions (filename, title, parent post), one-click apply with undo, decorative marking, and a Dashboard coverage card.
- New: editable suggestion box — apply the suggestion as-is or write your own words; hand-written text is capped and kept for undo like any apply.
- New: optional AI suggestions (BYOK) — per-image “Suggest with AI” with one-click presets (Gemini, OpenAI, Groq, OpenRouter), test connection, rate-limit handling, and cached answers. Reviewed before saving, off by default; rule-based suggestions never need it.
- New:
wp janitorix alt stats— read-only coverage report for the command line, with--format=jsonfor scripting. - New: “Remove key” checkbox in Settings — delete the stored API key without disabling anything else.
- Fixed: replacing an image under the same attachment ID no longer serves the previous file’s cached AI suggestion.
- Hardening: AI requests no longer follow HTTP redirects, so the API key stays with the configured endpoint.
- Improved: when the AI service declines, Test connection and the Alt Text screen now quote the service’s own reason (HTTP code + message) instead of only “answered unexpectedly”.
- Note: the alt text audit never touches confidence, risk, or deletion recommendations.
1.0.5
- Added: review notice (15-day) + footer rating link.
- Fixed: uninstall now removes the review state too.
- Performance: scanners build lazily (no cost on frontend views); version constant hardcoded.
1.0.4
- New: SEO and social image keys (Yoast, Rank Math, SEOPress) are now read as declared image fields, so an og:image stored as a bare attachment ID keeps its image referenced.
- Fixed: CSV formula injection in exports.
- Fixed:
SHOW TABLES LIKEescaping, delete-permanent rescan, and coverage floor handling. - Changed: Plugin URI, Author URI, short description and Packagist metadata now point at the author’s site.
1.0.3
- Fixed: an image used only in a widget, the Customizer or a theme option could be judged unused.
- Fixed: trashing or restoring an image asked for a rescan that was not needed.
- Fixed: a scanned image was reported as never scanned once the site had changed.
1.0.2
- Fixed: scanner accuracy bugs in Gutenberg, Widget, Generic Fallback, and ACF scanners.
- Fixed: SafetyEngine now reads verdicts from the current scan only.
- Fixed: AttachmentResolver no longer resolves external URLs by basename fallback.
- Fixed: GenericFallbackScanner now reports database errors instead of swallowing them silently.
- Fixed: outside_uploads no longer flags bare filenames without path separators.
- Fixed: ScanFingerprint no longer recomputes per row on the Images screen.
- Fixed: ImageValueExtractor no longer reports non-image attachments as missing.
- Fixed: Plugin Check security and database query warnings.
1.0.1
- Fixed: the author link on the Plugins screen went to a WordPress.org profile page instead of the author’s own site.
- Added: a link to the full guide in the plugin description.
1.0.0
- First stable release
- The Dashboard’s Confidence card read 0% on every scan — the figure was calculated and displayed but never stored
- An image held back because it was uploaded recently now says how much longer it stays protected, instead of only that it is
- The Images list shows each image’s upload date, which is also what the date filters above it match on
- Uninstall now removes the cached file hashes it wrote onto attachments, not only its tables, options and your saved decisions
- Risk Engine: a WooCommerce product’s gallery images are now priced at their correct impact instead of the lower, generic rate a field-name collision was giving them
- Risk Engine: the site logo, icon, header, and background are held at the highest risk level whenever the Customizer Scanner cannot confirm them — previously this floor was documented but not enforced
- Risk Engine: a store’s own placeholder image is now recognised and priced instead of going unnoticed
- Fixed a false “in use” reading on WooCommerce-imported images, caused by treating the import’s own source-URL metadata as a usage reference
- ACF: a Relationship field configured to browse only the Media Library is now trusted as image evidence, the same as an Image or Gallery field
- Scan History lists only finished scans, and now shows the storage each one actually recovered
- Delete Permanently’s confirmation is now enforced by the server, not only by the browser dialog
- A reminder to keep a recent backup, shown before a permanent delete
- The Images screen now labels a row it declines to offer for Trash as Protected, instead of leaving it blank
0.6.0
- The write path: Trash, Restore, and Permanent Delete, each gated by the Safety Engine
- A restore record is written before anything is touched, so recovery does not depend on WordPress having a media trash
- Bulk trash — every image still checked individually
0.5.0
- Calibration suite: seeded fixtures with known answers, run against the real pipeline
- A report of what would be deleted, having deleted nothing
0.4.0
- Dashboard, Images, Image Details, Scan History, Settings
0.3.0
- Risk Engine, Recommendation Engine, and the explanation layer
0.2.0
- Persistence, resumable batched scans, and fingerprint-based caching
0.1.0
- Scanner layer and Confidence Engine