PHPackages                             taurus-media/module-image-cleaner - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. taurus-media/module-image-cleaner

ActiveMagento2-module[Image & Media](/categories/media)

taurus-media/module-image-cleaner
=================================

Cleanup unused product images

1.0.0(2mo ago)016MITPHP

Since Apr 9Pushed 2mo agoCompare

[ Source](https://github.com/taurus-media/module-image-cleaner)[ Packagist](https://packagist.org/packages/taurus-media/module-image-cleaner)[ RSS](/packages/taurus-media-module-image-cleaner/feed)WikiDiscussions master Synced today

READMEChangelog (1)Dependencies (1)Versions (2)Used By (0)

Taurus\_ImageCleaner
====================

[](#taurus_imagecleaner)

A performance-optimized Magento 2 module to identify and remove unused product images.

Features
--------

[](#features)

- **Safe for Large Catalogs**: Uses a temporary database table to index used images, ensuring constant-time lookups.
- **Memory Efficient**: Uses PHP Generators and Iterators to stream files without loading them all into memory.
- **Batch Processing**: Supports batching and sleep intervals to minimize system load.
- **Trash-first Policy**: Unused images are moved to `var/image-cleaner-trash/` instead of being deleted immediately.
- **Automatic Cleanup**: A daily cron job automatically purges files from the trash that are older than 7 days.
- **Dry-run by Default**: Safety first—no images are moved unless the `--delete` flag is explicitly provided and confirmed.

Installation
------------

[](#installation)

Place the module code in `app/code/Taurus/ImageCleaner`.

```
bin/magento module:enable Taurus_ImageCleaner
bin/magento setup:upgrade
```

Usage
-----

[](#usage)

### Commands

[](#commands)

**Basic Dry-Run:**

```
bin/magento catalog:image:cleanup
```

**Actually Move Unused Images to Trash:**

```
bin/magento catalog:image:cleanup --delete
```

**Advanced Usage:**

```
bin/magento catalog:image:cleanup --delete --batch-size=1000 --sleep=1 --output-file=unused_images.log
```

### Options

[](#options)

- `--dry-run`: (Default) Scans and reports unused images without moving them.
- `--delete`: Enables moving unused images to trash (`var/image-cleaner-trash/`). Requires manual confirmation.
- `--batch-size=`: Number of images to process before sleeping/logging (default: 5000).
- `--sleep=`: Seconds to sleep between batches (default: 0).
- `--output-file=`: Path (relative to `var/`) to log the list of unused images.

Trash & Recovery
--------------------

[](#trash--recovery)

When running with `--delete`, images are moved to `var/image-cleaner-trash/`. If you accidentally move images that should have been kept, you can move them back to `pub/media/catalog/product/`.

A cron job `taurus_image_cleaner_trash_purge` runs daily at 01:00 and deletes files from the trash that are older than 7 days.

How it Works
------------

[](#how-it-works)

1. **Indexing**: The module creates a temporary table `taurus_image_cleaner_used_images`.
2. **Collection**: It populates this table with image paths from:
    - `catalog_product_entity_media_gallery` (Media gallery entries)
    - `catalog_product_entity_varchar` (Main image, small image, thumbnail, and swatch image attributes)
3. **Scanning**: It uses `RecursiveDirectoryIterator` to scan `pub/media/catalog/product/`.
4. **Validation**: For each file, it performs a fast indexed lookup against the temporary table.
5. **Action**: If an image is not found in the index, it's marked as unused and optionally moved to trash.
6. **Cleanup**: The temporary database table is dropped after the process completes.
7. **Maintenance**: A cron job cleans up the trash folder periodically.

Safety & Warnings
---------------------

[](#safety--warnings)

- **Backup Recommended**: Always back up your `pub/media/catalog/product` directory and your database before running with the `--delete` flag in a production environment.
- **Excluded Directories**: The module automatically ignores `watermark`, `tmp`, `placeholder`, and other temporary directories.
- **Cache Scanning**: The module now also scans the `pub/media/catalog/product/cache` directory. Cached images are considered unused if their corresponding original product image is not found in the database.
- **Normalized Paths**: Only images following the Magento standard structure `pub/media/catalog/product/[a-z0-9]/[a-z0-9]/...` are processed.

Requirements
------------

[](#requirements)

- Magento 2.4+
- PHP 8.1+

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance83

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity34

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

86d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/9a63921d7d7fd387db50f9e01c25123205ad89de7a50c0c95ea2ba4061cc4b26?d=identicon)[taurus-media](/maintainers/taurus-media)

---

Top Contributors

[![ytaurvl](https://avatars.githubusercontent.com/u/141410251?v=4)](https://github.com/ytaurvl "ytaurvl (2 commits)")

### Embed Badge

![Health badge](/badges/taurus-media-module-image-cleaner/health.svg)

```
[![Health](https://phpackages.com/badges/taurus-media-module-image-cleaner/health.svg)](https://phpackages.com/packages/taurus-media-module-image-cleaner)
```

###  Alternatives

[smile/elasticsuite

Magento 2 merchandising and search engine built on ElasticSearch

8064.7M49](/packages/smile-elasticsuite)[mollie/magento2

Mollie Payment Module for Magento 2

1131.9M16](/packages/mollie-magento2)[yireo/magento2-next-gen-images

Magento 2 module to add NextGen images support to the Magento frontend

471.2M2](/packages/yireo-magento2-next-gen-images)[smile/module-product-label

Smile - Extension of Magento2 to be able to contribute images associated to product attribute values.

58101.5k](/packages/smile-module-product-label)[emico/m2-attributelanding

Attribute landing pages for Magento 2

17263.2k10](/packages/emico-m2-attributelanding)[mage-os/module-automatic-translation

Automatic AI content translation for Mage-OS.

3017.9k](/packages/mage-os-module-automatic-translation)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)