# baldwin/magento2-module-image-cleanup > Magento 2 module which can cleanup old image files that are no longer being used `composer require baldwin/magento2-module-image-cleanup` Canonical URL: https://packagento.com/baldwin/magento2-module-image-cleanup ## At a glance - **Vendor**: baldwin (https://packagento.com/baldwin.md) - **Latest version**: 1.2.7 — released 2026-04-14 - **Pricing**: Free - **Package type**: Magento 2 module - **Status**: active, accepting new buyers ## Installation Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them. 1. **Sign in or create an account** at https://packagento.com/customer/account/. 2. **Add the package to your account.** Open https://packagento.com/baldwin/magento2-module-image-cleanup and complete the free checkout. A licence is minted automatically. 3. **Create or pick a project, then activate the licence on it.** - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/. - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project. 4. **Add the project credentials to your Magento codebase.** Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`: ```json { "http-basic": { "packagento.com": { "username": "ppk_live_...", "password": "psk_live_..." } } } ``` Add the Packagento Composer repository to `composer.json`: ```json { "repositories": [ { "type": "composer", "url": "https://packagento.com" } ] } ``` 5. **Install and apply.** ```bash composer require baldwin/magento2-module-image-cleanup:* bin/magento setup:upgrade bin/magento setup:di:compile bin/magento cache:flush ``` ## What it does Magento 2 module which can cleanup old image files that are no longer being used ## README ### Purpose When adding products in your webshop, eventually you'll also have to delete some of those products. But sometimes Magento doesn't remove images associated with the products that you delete. So you'll have to manually delete them from time to time from disk, which is hard to do manually. This module gives you some options to delete those lingering unused images from the disk so you can recover some diskspace on your server. ### Implemented Features - It can find product image files on disk that are not referenced in the database and remove them - It can do the same for the resized (cached) versions of those images - It tries to not delete dynamically generated images files (like `webp` of `avif` files) if the original file is still being used, see [configuration](#configuration) - It can detect entire unused resized (cached) directories that are no longer valid and remove them with all the files in there, see [below](#documentation-about-resizedcached-directories) - It can detect and remove obsolete values in the `catalog_product_entity_media_gallery` database table - It can find resized product image files that are corrupt and remove them ### Watch out - The module will always first output what it will delete, make sure you check the entire list before confirming, so that you aren't removing files you don't want to remove. Do **not** _test_ this module on a production environment first before you fully understand what it will do! - This module hasn't been tested when your Magento shop is configured to store image files in the database, your mileage may vary when you use that way of working. Feel free to open issues in case any occur, and we'll see if we can fix something... ### Compatibility - This module should work with Magento 2.3.4 or higher - The module should be compatible with PHP 7.3, 7.4, 8.1, 8.2, 8.3 and 8.4 ### Installation You can use composer to install this module: ```sh composer require baldwin/magento2-module-image-cleanup ``` Or download the code and put all the files in the directory `app/code/Baldwin/ImageCleanup` After which you can then activate it in Magento using: ```sh bin/magento setup:upgrade ``` ### Usage There are 4 command line commands you can use execute: - `bin/magento catalog:images:remove-obsolete-db-entries` - `bin/magento catalog:images:remove-unused-hash-directories` - `bin/magento catalog:images:remove-unused-files` - `bin/magento catalog:images:remove-corrupt-resized-files` There are some extra options for some of these commands: ``` --no-stats Skip calculating and outputting stats (filesizes, number of files, ...), this can speed up the command in case it runs slowly. -n, --no-interaction Do not ask any interactive question ``` The `-n` option can be used if you want to setup a cronjob to regularly call these cleanup commands, it will not ask for confirmation before removing files, and will just assume you said 'yes, go ahead' (which can be dangerous!) The module will output all the things it deleted in a log file `{magento-project}/var/log/baldwin-imagecleanup.log` so you can inspect it later in case you want to figure out why something got removed. For optimal & fastest cleanup, it's advised to run the commands in this order: 1. `bin/magento catalog:images:remove-obsolete-db-entries` 2. `bin/magento catalog:images:remove-unused-hash-directories` 3. `bin/magento catalog:images:remove-unused-files` 4. `bin/magento catalog:images:remove-corrupt-resized-files` If you don't run these in this order, it might mean you'll need to run some of them a second time for them to find more things to cleanup or it might mean that they'll take longer then needed. ### Configuration There is a configuration section in the backoffice under: Stores > Configuration > Catalog > Catalog > Product Image Cleanup Settings - **List of dynamically generated image file extensions**: Some Magento shops might have modules installed to dynamically generate `webp` or `avif` image files out of the original product image files. These files are usually not referenced in the database of Magento so by specifying those file extensions in the configuration, we can prevent them from being deleted accidentally. The module will still be able to remove those type of files when the original file is no longer referenced in the database. This feature only works properly when the dynamically generated image files use the same filename as the original file, so they can only be different in the file extension being used (either replaced or appended). ### Documentation about resized/cached directories Magento saves resized product images in certain directories in `pub/media/catalog/product/cache` The directory names are basically an md5 hash of a bunch of parameters like: width, height, background-color, quality, rotation, ... (which tend to be defined in the `etc/view.xml` file of themes) Sometimes, Magento tweaks how the hash gets calculated in certain newer versions of Magento, or your theme changes some parameter which both can make those hashes no longer being used. This module has the option to detect such directories and can remove them together with all the files in there. ### Note to self In our class `Baldwin\ImageCleanup\Finder\UnusedCacheHashDirectoriesFinder`, we borrowed some code from core Magento that was private and not easily callable. We made only very slight changes to deal with coding standards and static analysis, but it's mostly the same as the original source. These pieces of code were based on code that didn't really change since Magento 2.3.4. It's important that we check with every single new Magento version that gets released, that the code in `Magento\MediaStorage\Service\ImageResize` doesn't change in such a way that we need to adapt our own implementation. So this is something that needs to be double checked with every new Magento release. ## Recent Versions | Version | Released | |---|---| | 1.2.7 | 2026-04-14 | | 1.2.6 | 2025-04-11 | | 1.2.5 | 2025-04-09 | | 1.2.4 | 2024-08-27 | | 1.2.3 | 2024-03-22 | | 1.2.2 | 2023-09-26 | | 1.2.1 | 2023-09-20 | | 1.2.0 | 2023-09-20 | | 1.1.0 | 2023-04-21 | | 1.0.2 | 2023-03-01 | Showing 10 of 12 versions. Full release history on https://packagento.com/baldwin/magento2-module-image-cleanup. ## Dependencies ### Require | Package | Constraint | |---|---| | magento/framework | ^102.0.4 \|\| ^103.0 | | magento/module-catalog | ^103.0.4 \|\| ^104.0 | | magento/module-eav | ^102.0.4 | | magento/module-store | ^101.0.4 | | magento/module-theme | ^101.0.4 | | php | ~7.3.0 \|\| ~7.4.0 \|\| ~8.1.0 \|\| ~8.2.0 \|\| ~8.3.0 \|\| ~8.4.0 \|\| ~8.5.0 | | symfony/console | ^4.0 \|\| ^5.0 \|\| ^6.0 \|\| ^7.0 | ### Require (dev) | Package | Constraint | |---|---| | bamarni/composer-bin-plugin | ^1.7 | | ergebnis/composer-normalize | ^2.17 | ## Quality Latest release (1.2.7) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers. ### Compatibility Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`. | Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 | |---|---|---|---|---| | 2.4.7 | Pass | Pass | – | – | | 2.4.8 | – | Pass | Pass | – | | 2.4.9 | – | – | Pass | Pass | ### Code Quality Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible. #### Static Analysis Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module. | Tool | Status | Findings | Summary | |---|---|---|---| | PHPCS | Warning | 48 | 48 warnings (ruleset: Magento2) | | PHPMD | Warning | 9 | 9 rule violations (MissingImport:8, UnusedLocalVariable:1) | | Cpd | Pass | 0 | | | Composer validate | Pass | 0 | | #### PHPStan Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases. | Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 | |---|---|---|---|---| | 2.4.7 | 6 | 6 | – | – | | 2.4.8 | – | 6 | 6 | – | | 2.4.9 | – | – | 6 | 6 | ### Tests Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately. #### Unit Tests | Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 | |---|---|---|---|---| | 2.4.7 | N/A | N/A | – | – | | 2.4.8 | – | N/A | N/A | – | | 2.4.9 | – | – | N/A | N/A | #### Integration Tests | Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 | |---|---|---|---|---| | 2.4.7 | N/A | N/A | – | – | | 2.4.8 | – | N/A | N/A | – | | 2.4.9 | – | – | N/A | N/A | ### Security Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright. | Tool | Status | Findings | Summary | |---|---|---|---| | Composer audit | Pass | 0 | | | Malware scan | Pass | 0 | | ## Licence and pricing Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step. Refundable within 14 days of first purchase via https://packagento.com/account/refunds/. ## Install via Claude Code or any MCP client The Packagento MCP server can run the licence + project + Composer steps above in one tool call: ``` purchase_and_install_packages( composer_names=["baldwin/magento2-module-image-cleanup"], project_id="proj_xxx" ) ``` This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup. ## Vendor baldwin is a Magento 2 vendor on Packagento. See https://packagento.com/baldwin.md for their full catalogue.