Check it fits your store
Questions about compatibility? Contact us.
Details
Media Cleaner is a Magento 2 extension that finds and removes unused product, category, and content images from pub/media. Review leftover files, protect images you want to keep, and use a private recovery bin to restore removed images.
Find unused images with Media Cleaner
Start a scan from the Admin to check image references across your store:
- Product galleries, product and category image attributes, and descriptions.
- CMS pages and blocks, Page Builder content and templates, and widgets.
- Configuration values, email and newsletter templates, and text columns in other extensions' tables.
- Theme and module files in app/design and app/code, style sheets in pub/media, and Magento's media content index.
The scan recognizes media directives, full and CDN URLs, resized-image URLs, escaped Page Builder content, and URL-encoded or plain file names. A bare file name protects every image with that name. A progress bar shows each step, and the scan continues in the background when you leave the page.
Review results and protect images
Review unused images with previews, folders, sizes, and dates. Filter by products, categories, or content, then search and sort the results. Recently added images appear separately and are never removed automatically; the default recent-image period is 7 days.
The In use view shows where each image was first found. Usage counts show how many images each source keeps, with an option to ignore tables that only list files. Add images used only outside the store to the keep list to protect them from removal.
Choose recovery before cleanup
The extension checks each file again before removal. Choose a private recovery bin outside the public media folder with a retention period of 7 or 30 days, or choose immediate deletion. Restore binned images with one click; restored images automatically join the keep list.
Clean cache and schedule maintenance
Remove resized image cache older than 7, 30, or 90 days. The extension keeps and lists cached images whose original is missing.
Use buttons to turn scheduling off or select daily, weekly, or monthly cleanup. Choose the day, a quiet hour, what to remove, the minimum image age, and recovery time. A summary explains the plan and shows the next run.
- Run now executes the plan with a progress bar.
- Admin notifications report freed space and failed runs.
- History lists recent scans and cleanups.
- Command-line tools support scanning, scanning and cleaning, cache-only cleanup, and recovery bin restoration and purging.
Download, editions, and requirements
Includes the version 2.1.2 digital download. Choose the Community, Enterprise, or Magento Cloud edition.
- Platform: Magento Open Source / Adobe Commerce 2.4.9.
- PHP: 8.3–8.5.
- Database: MySQL 8 or MariaDB 10.6+.
- Storage: media must reside in pub/media on the server. Remote storage such as S3 and database media storage are not supported.
- Cron: Magento cron must run for scheduled cleanups and scans that continue in the background.
The extension runs only in the Admin, cron, and command line and adds nothing to the storefront. It works with any storefront theme, including Luma, Luma-based themes, and Hyvä. The scan also checks Hyvä child themes in app/design for image references.
Change Log
Version 2.1.2 – October 30, 2026
Other changes
- Documentation: Media Cleaner is theme-independent and works with Luma, Luma-based and Hyvä storefronts (it works in the Admin, the cron and the command line only and adds nothing to the storefront). Hyvä child themes in app/design are checked for image references like any other theme. No code changes.
Earlier versions (4)
Version 2.1.1
Other changes
- Installing or upgrading in developer mode failed with "The XML in file .../MediaCleaner/etc/db_schema.xml is invalid: ... The value '1100' is greater than the maximum value allowed ('1024')". Magento allows varchar columns up to 1024 characters and checks this only in developer mode. The recovery bin's stored_as column (the run ID plus the image path, which can be longer than 1024 characters) is now a text column; setup:upgrade converts existing tables without losing data.
Version 2.1.0
Other changes
- Recently added images that are not used anywhere (for example images of a product you just deleted) can be removed: select them under Recently added and choose Remove, or Remove all there. The dialog reminds that they are new. Scheduled cleanups, the command line and Remove all under Unused still leave them alone. Cleanup selection recent (admin only).
Version 2.0.0
Other changes
- Rebuilt so scans finish quickly on large stores and unused images can be removed.
- Fast, targeted reference check: product galleries of existing products, the media content index, one filtered pass per database table (logs, indexes, sessions, queues, orders and file registries skipped), and theme and module files instead of the whole codebase. Version 1 always reached its time or size limit and could not clean.
- Resumable steps: progress bar in the Admin; scans and cleanups continue in cron when the page is closed.
- Results per file with previews: filters by folder and state, search, sort, "In use" with the place each image was found, keep list, bulk remove.
- Image cache: orphaned copies, cache older than 7/30/90 days, thumbnails, and copies still shown although their original is missing (kept and reported).
- "Where images are used": images kept per place; ignore a table with one click.
- Recovery bin with previews, restore (adds to the keep list), delete and empty; 0, 7 or 30 days.
- Schedule with buttons only: frequency, weekday or day of month, time, what to remove, age limit and recovery days; summary sentence, next run, Run now; Admin notification after each scheduled cleanup.
- Removed originals take their resized copies and thumbnails with them; media gallery records and empty folders are cleaned up.
- WebP/AVIF copies next to used images are kept.
- History of the last 30 runs.
- CLI: techimprovement:media:scan [--clean] [--no-cache] [--cache-only] and techimprovement:media:recovery.
- Version 1 schedules are migrated; the version 1 item table and columns are removed.
Version 1.2.0
Other changes
- Run Admin previews through an isolated cron worker with automatic status polling.
- Add bounded 3-, 10- and 20-minute reference-check presets, defaulting to 10 minutes.
- Replace small primary-key table OFFSET pages with bounded keyset batches while preserving complete text/blob reads and text charset conversion.
- Show the actual failed stage, relative path or budget and next steps; keep the primary blocker when warning lists fill.
- Exclude known secret links before resolving them, while continuing to block unsafe managed-media links.
- Start candidate verification's separate time budget at its first fingerprint.
- Give Media Cleaner its own section under Content, outside Elements.
Reviews
Be the first to review Media Cleaner
Reviews are written by customers with an account. Sign in to tell others how it works on your store.
