Installation
Before installing the extension, please make sure to Backup your web directory and store database
You will require to install MageDelight Base Extension first. If it is not installed then please download it from https://www.magedelight.com/pub/extensions/magedelight-base.zip and unzip the package file into the root folder of your Magento 2 installation.
Root Directory is - "app/code/magedelight/#YourExtensionName#"
- Unzip the extension package file into the root folder of your Magento 2 installation.
- Connect to SSH console of your server:
- Navigate to the root folder of your Magento 2 setup
Run command as per below sequence,
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento cache:clean
- log out from the backend and log in again
If you are using Magento 2.3 or later then you do not need to activate license. Extension will be activated with silent activation mechanism and does not require activation keys to be entered manually.
Backend Configuration (Admin side)
| Field | Description |
|---|---|
| Enable | This option allows you to activate or deactivate the Image Cleanup extension for the selected website scope. • Set “Yes” to enable all features of the module, including image detection, trash system, and cleanup operations. • Set “No” to temporarily disable the extension without uninstalling it. Disabling the module stops all automated CRON scans and cleanup processes. |
| Image Trash Folder Path | Defines the storage path where unused images will be safely moved when sent to the trash instead of being deleted permanently. By default, the folder path is: var/trash/imagecleanup This path is inside the Magento media directory, ensuring that images remain accessible for restore operations. You can customizethe folder name if required (for example, var/trash/media_cleanup). Always make sure the specified directory has read/write permissions for Magento’s file system user. |
| Field | Description |
|---|---|
| Auto Cleanup | Enables or disables automatic image cleanup via CRON. When set to “Yes”, the extension automatically performs cleanup actions (move or delete) based on the configured schedule. |
| Clean up Action | Defines what the automated cleanup should do with the detected unused images. Available options: • Move to Trash – Automatically transfers all unused images to the trash folder for safe review before deletion. • Delete Permanently – Automatically deletes unused images from the system and trash folder with no restore option. Use “Move to Trash” for safer operation and “Delete Permanently” for aggressive cleanup. |
| Clean up Frequency | Determines how often the automatic cleanup job runs through CRON. Available values: • Daily – Runs every day at the set time. • Weekly – Runs once a week. • Monthly – Runs once a month. Choose a frequency that aligns with your store’s image update rate and maintenance policy. |
| Clean up Time | Sets the exact time (HH:MM: SS) for the CRON job to start the cleanup operation. Example: 02:00:00 will execute cleanup daily/weekly/monthly at 2 AM. It is recommended to schedule cleanup during low-traffic hours to avoid performance impact on your live store. |
The cleanup process automatically handles the removal of the unused images identified during the scan.
- Functionality: A dedicated cron job moves unused images either to the Trash folder or Deletes them Permanently, based on the Cleanup Action configured in the extension's settings.
- Configuration:
- Once Auto Cleanup is enabled, images will be automatically moved to trash or permanently deleted from the trash.
- Set the Cron Frequency and Cleanup time to run after the Auto Scanning cron has completed its task.
⚠️ Important for Permanent Deletion: For images to be permanently deleted, they must not be present in the Restore & Delete Permanently grid. This acts as a final safeguard.
⚠️ Important for Move to Trash: For images to be moved to trash, they must be scanned First in the Unused Image grid.
| Field | Description |
|---|---|
| Auto Scan Enable | Enables or disables the automatic image scanning process through CRON.When set to “Yes”, Magento will automatically run the scan process for images at the defined frequency and time. This ensures your image database remains up to date without requiring manual initiation of the scan. |
| Auto Scanning / Refresh | Allows you to choose the specific types of scans that should be performed automatically. Available options: • Product Scan – Scans all product images to identify unused or missing files. • CMS Scan – Scans CMS pages and blocks for unused or broken image references .• Category Scan – Scans category-level images for detection and verification. Multiple options can be selected to perform combined scanning operations in a single CRON cycle. |
| Scan Frequency | Defines how often the automatic image scanning process runs via CRON. Available values: • Daily – Runs every day. • Weekly – Runs once a week. • Monthly – Runs once a month. Select a frequency based on your media update rate and business maintenance policy. |
| Scan Time | Specifies the exact time (HH:MM:SS) at which the automatic scan should begin. Example: It is recommended to set scanning during off-peak hours to minimize performance impact on live customers. |
This process identifies and lists unused images on your store.
Command Line Interface (CLI): You can trigger a scan manually using the following command, specifying the image type:
Bash : php bin/magento magedelight:imagecleanup:scan
- Options: Use the -t or --type option to specify the target images:
- --type[=TYPE] : Type of images to scan (e.g., product, cms, missing, or all).
- Default: "all"
- Cron Job (Auto Scanning): For continuous, automated monitoring, set up the cron job:
- Navigate to Configuration > Magedelight > Image Cleanup > Auto Image Scanning.
- Enable auto scanning, select the desired image types for the scan, and configure the Cron Frequency and time.
⚠️ Important: Ensure all unused images are scanned and correctly listed in the grid before initiating the cleanup/move to trash operation.
| Field | Description |
|---|---|
| Email Notifications | Enables or disables the email notification system for the Image Cleanup extension. When set to “Yes”, the system automatically sends an email update after every scheduled cleanup job (based on CRON execution). These emails summarise operation results — including the number of images moved, deleted, or any issues detected during the process. |
| Notification Email Address(es) | Specify one or more recipient email addresses to receive cleanup notifications. Use a comma (, ) separator to add multiple addresses (e.g., Ensure the listed email addresses belong to team members responsible for monitoring store maintenance or DevOps activities. |
| Email Template for Success | Selects which email template to use when a scheduled cleanup completes successfully. Default Template: Image Cleanup Success (Default) This email includes details such as: • Date/time of cleanup • Total images processed • Space saved • Next scheduled run time |
| Email Template for Failure | Defines the template used when a cleanup job fails due to an error or incomplete process. Default Template: Image Cleanup Failure (Default) This alert helps administrators quickly identify and resolve CRON or permission issues that prevent cleanup completion. Recommended for proactive system monitoring and maintenance tracking. |
| Field | Description |
|---|---|
| Set Batch Size | Defines the number of images processed in a single batch during scan or cleanup operations. Example: If set to 100, the extension will process 100 images per cycle before proceeding to the next batch. Adjust this value based on your server’s capacity and media directory size — lower for limited resources, higher for powerful servers. |
| Enable Logs | Enables or disables the logging system for all image cleanup activities. When set to “Yes”, detailed logs are stored in:
Each log entry contains the image name, path, admin username, action (deleted/moved), and date/time of the operation. These logs help administrators track actions and audit cleanup history for troubleshooting or verification. |
| Enable CRON for Logs Auto Cleaning | If enabled, the system will automatically clear old log entries based on the defined retention period. This prevents log files from becoming excessively large and consuming unnecessary disk space. |
| Auto-Delete Logs Older than Days | Defines the retention period (in days) for log records. Example: If set to 7, logs older than 7 days will be deleted automatically. Helps maintain optimal performance and ensures only recent logs are retained. |
| CRON Frequency | Sets how often the log auto-cleaning CRON job will execute. Available values: • Daily – Runs every day. • Weekly – Runs once a week. • Monthly – Runs once a month. Recommended: Daily to keep logs lean and current. |
| CRON Time | Specifies the time of day (HH:MM:SS) when the CRON job for log auto-cleaning should run. Example: Schedule during off-peak hours to minimize server load impact. |
Backend Functionality
Image Cleanup Dashboard
- The Image Cleanup Dashboard provides a centralized overview of your store’s image optimization activities.
- It displays real-time statistics on unused images, trash operations, restored files, deleted files, and scheduled cleanup jobs.
- This helps administrators track the effectiveness of image maintenance tasks, assess potential space savings, and monitor automation via CRON schedules.
- Path: Magedelight → Image Cleanup → Dashboard
| Section / Field | Description |
|---|---|
| Total Unused Images | Displays the total count and size of all unused images detected across Product, CMS, and Category sections. Example: |
| Images in Trash | Shows the number and total size of images currently stored in the trash folder. This indicates files awaiting review before permanent deletion. |
| Images Restored | Displays the count of images that were restored from trash back to their original locations. Useful for tracking accidental deletions or verified image recoveries. |
| Images Deleted | Indicates how many images have been permanently deleted from the system after review or CRON cleanup. |
| Space Reclaimed | Shows the total storage space that has been freed after permanently deleting unused images. This metric helps in assessing hosting and storage optimization. |
| Potential Space Savings | Estimates how much space can be reclaimed if all currently unused images are deleted. This helps in planning cleanup actions and capacity management. |
| Moved to Trash Details | Provides a breakdown of how many images from each module (Product, CMS, Category) have been moved to trash. Gives clarity on where most unused images originate. |
| Permanently Deleted Details | Lists the number of images permanently deleted per module type — Product, CMS, and Category — along with total reclaimed space per category. |
| Monthly Image Restoration Trends | Displays a visual bar chart showing the number of images restored month-wise. This helps you analyze restore activities and recovery trends over time. |
| Scheduled Jobs Status | Lists all configured CRON jobs related to image cleanup, including job name, enable status, CRON state, and timestamps for creation, scheduling, and execution. If no jobs appear, it means automatic cleanup or scanning has not been configured yet. |
Usage Tip: Regularly review the Dashboard to evaluate cleanup effectiveness, space utilization trends, and ensure CRON-based automations (for scan and cleanup) are running successfully.
Cleanup Management
Product Images Cleanup
- The Product Images Cleanup section allows administrators to scan, review, and manage unused product images stored in the Magento media directory.
- This tool helps you identify images that are no longer associated with any catalog products and safely move them to trash or delete them permanently.
- It provides real-time scan progress, a batch-based processing log, and a grid view listing all unused images for quick review and action.
- Path: Magedelight → Image Cleanup → Cleanup Management → Product Images
| Section / Field | Description |
|---|---|
| Start Scan | Begins the image scanning process for product images. When clicked, the system starts analyzing the media directory to identify images that are not associated with any products in the catalog. Note: Do not close the window until the scan is complete, as it runs in the active browser session. |
| Move All to Trash | Moves all unused product images found during the scan to the Trash Folder instead of deleting them immediately. This provides a safe intermediate step, allowing you to review or restore images later from the Trash before permanent removal. |
| Delete All Images | Permanently deletes all unused product images detected during the scan. Use this option only after reviewing the scan results, as the images removed by this action cannot be recovered unless backed up. |
| Image Scan Progress – Product | Displays real-time progress of the ongoing product image scan. It includes batch count, number of processed images, and number of unused images detected. Each operation’s details appear in the Processing Log, helping you track performance and progress. |
| Scan Mode (Foreground) | Indicates the scan is running in foreground mode, meaning it is actively processed within the browser session. Background mode (if available) would run asynchronously via CRON jobs. |
| Current Batch | Displays the batch number currently being processed. Batch processing ensures that the scan runs efficiently, handling a manageable number of images at a time based on the configured batch size. |
| Images Processed | Shows the total number of images that have been scanned so far, including both used and unused images. |
| Unused Images Found | Indicates how many images are not linked to any product, category, or CMS reference. These are candidates for cleanup or trashing. |
| Processing Log | Provides a live status feed of scan progress. Each entry shows: • Batch number processed • Number of images scanned • Number of unused images found • Final completion summary This helps administrators confirm that all batches were scanned successfully. |
| Grid View (Results Table) | Displays the detailed list of all unused images found. Each row contains the following details: • Image – Thumbnail preview of the unused image. • Path – File path in the Magento media directory .• Size – File size in KB or MB. • Image Type – File format (JPG, PNG, etc.). • Created At – Timestamp of when the image was originally uploaded. • Action – Dropdown menu to perform individual operations such as Move to Trash, Delete Permanently, or View in Folder. |
| Filters & Columns | Use these controls to filter unused images by size, type, or creation date, and customize visible columns in the grid. This helps in reviewing only relevant items before performing bulk operations. |
Usage Tip: Perform a manual scan first and review the grid before enabling Auto Image Cleanup (CRON). This helps validate that the extension correctly identifies unused media in your specific store setup.
CMS Image Cleanup
- The CMS Image Cleanup section helps administrators identify and manage unused images associated with CMS Pages and CMS Blocks.
- It scans the media directory to locate images that are uploaded but not linked to any CMS content, allowing you to safely move them to trash or permanently delete them.
- This ensures your CMS media library remains clean, lightweight, and well-organized — improving both storage efficiency and site performance.
- Path:Magedelight → Image Cleanup → Cleanup Management → CMS Images
| Section / Field | Description |
|---|---|
| Start Scan | Initiates the CMS image scanning process to detect unused files. The scan reviews CMS Pages and Blocks for any unreferenced images. |
| Move All to Trash | Moves all unused CMS images found during the scan into the trash folder. This option allows a safe rollback if needed before deletion. |
| Delete All Images | Permanently deletes all detected unused CMS images from the media directory. Use with caution, as deleted files cannot be restored. |
| Image Scan Progress – CMS | Displays real-time progress including batch number, total images scanned, and unused images found. |
| Processing Log | Shows live scanning activity, including number of images processed per batch, unused images detected, and final completion status. |
| Grid View (Results Table) | Lists all unused CMS images with details such as image name, path, size, type, creation date, and available actions (Move to Trash, Delete Permanently, etc.). |
| Filters & Columns | Use to filter results by size, type, or date, and customize visible columns for efficient review and management. |
Usage Tip: Perform CMS cleanup regularly (e.g., monthly) to prevent the accumulation of outdated banner or content images. This improves backup performance and reduces hosting costs.
Category Image Cleanup
- Scans and lists unused category images with live counts and logs.
- From the grid, you can Start Scan, then Move to Trash / Restore / Delete selected images using filters and per-row actions.
- Path: Magedelight → Image Cleanup → Cleanup Management → Category Image → Category Image Cleanup
| Field / Section | Description |
|---|---|
| Page Title: Category Image Cleanup | Indicates the current module section being used — specifically for cleaning up unused category images in Magento. |
| Action Buttons | Move All To Trash, Delete All Images, and Start Scan — primary controls to manage detected images. “Start Scan” initiates a new scan for unused images. |
| Warning Message | A yellow alert box reminding the admin not to close the window until the scan process completes. |
| Info Message | A blue information note explaining that this section shows images uploaded to the directory but not assigned to any category pages. |
| Image Scan Progress (Category) | Displays the scan summary for the current run, including batch count, number of images processed, and unused images found. |
| Current Batch | Displays the current batch number being processed (e.g., Batch 1). |
| Images Processed | Total number of images scanned during the current operation (e.g., 23). |
| Unused Images Found | Number of images detected as unused (e.g., 23). |
| Processing Log | A real-time log panel displaying each step of the scan — initialization, data loading, processing results, and completion messages. Logs appear in green text with timestamps for transparency and debugging. |
| Actions Dropdown | Allows bulk operations (e.g., move selected images to trash or delete). |
| Grid/Table Section | Displays the list of identified unused images with detailed information for each entry. |
| Image | Thumbnail preview of the unused image file. |
| Image Name | The file name of the image (e.g., 813MIZWXKL.jpg). |
| Path | Directory path of the image within Magento’s media folder (e.g., |
| Size | File size of the image (e.g., 367.439 KB). |
| Extension Type | Image file format (e.g., JPG). |
| Created At | Timestamp showing when the image was uploaded or created in the system. |
| Action (per record) | Dropdown menu with options like Move to Trash, Restore, or Delete for individual image management. |
| Filters / Columns / Default View | Toolbar controls allowing admins to filter results, customize visible columns, or reset to the default grid layout. |
| Pagination Controls | Allows navigation between multiple pages of scan results (e.g., “2 per page”, “1 of 12”). |
Run the scan during low-traffic hours to avoid performance impact. Always review images in the trash before permanent deletion to ensure no important category assets are removed.
Missing Images
Product Missing Images
- Scans and lists missing image references on products (by name and SKU).
- Use the grid to review affected items and upload the missing images directly from the Action column.
- Path: Magedelight → Missing Images → Missing Product Images → Product Missing Images
| Field | Description |
|---|---|
| Page Title | Section to detect and list missing product images across the catalog. |
| Start Scan | Triggers a scan to find product image references that are absent from the media directory. |
| Info Note | Explains that listed items are referenced on products but not present in |
| Current Batch | Batch number currently being processed. |
| Total Processed | Number of product image references scanned. |
| Missing Images Found | Count of missing product images detected. |
| Processing Log | Real-time log of scan initialization, progress, and completion (with timestamps). |
| Grid/Table Section | Results list for review and action. |
| ID | Record index. |
| Missing Path | Expected media path of the missing product image. |
| Image Name | Filename of the missing image. |
| Source | Product where the image is referenced (Product name and SKU). |
| Detected At | Timestamp when the missing reference was identified. |
| Action (Upload Image) | Quick link to re-upload the missing image for that product. |
| Filters / Columns / Pagination | Tools to filter results, choose visible columns, and navigate pages. |
Run this after product imports/migrations to catch broken media. After uploading, flush cache/CDN and re-scan to confirm the product images render correctly on the storefront.
CMS Missing Images
- Scans and lists missing image references within CMS Pages and Blocks.
- Admins can review missing paths, identify affected sources, and upload the missing images directly from the grid.
- Path: Magedelight → Missing Images → Missing CMS Images → CMS Missing Images
| Field / Section | Description |
|---|---|
| Page Title | Displays the section for detecting missing CMS images across pages and blocks. |
| Action Button (Start Scan) | Initiates the scan to detect missing or deleted images referenced in CMS pages or blocks. |
| Information Note | Explains that this section lists image paths that are referenced but not available in the media directory. |
| Current Batch | Indicates the current batch number of the scan process. |
| Total Processed | Shows the total number of CMS image paths scanned. |
| Missing Images Found | Displays how many CMS image paths were found missing. |
| Processing Log | Real-time log panel showing scan initialization, progress, and completion messages with timestamps. |
| Grid/Table Section | Displays the list of detected missing CMS images for admin review. |
| ID | Serial number of each missing image record. |
| Missing Path | Shows the missing file path in the media directory. |
| Image Name | Displays the name of the missing image file. |
| Source | Indicates where the missing image is referenced (e.g., CMS Page or Block ID). |
| Source Type | Specifies whether the source is a CMS Page or CMS Block. |
| Detected At | Timestamp of when the missing image reference was identified. |
| Action (Upload Image) | Provides a quick action link to re-upload the missing image directly from the grid. |
| Filters / Columns / Pagination | Allows filtering, customizing columns, and navigating through multiple pages of results. |
Run this scan periodically to ensure CMS pages and blocks are free from broken image links, improving both user experience and store presentation quality.
Category Missing Images
- Scans and lists missing image references in product categories.
- Admins can review the affected categories and upload the missing images directly from the grid to restore visuals.
- Path: Magedelight → Missing Images → Missing Category Images → Category Missing Images
| Field / Section | Description |
|---|---|
| Path | Magedelight → Missing Images → Missing Category Images → Category Missing Images |
| Page Title | Section used to detect and list missing category images across the Magento store. |
| Start Scan | Initiates the scan to identify category image references that are missing from the media directory. |
| Info Note | Explains that this section lists images referenced in categories but not available in |
| Current Batch | Shows the current batch being scanned. |
| Total Processed | Displays the total number of category image references scanned. |
| Missing Images Found | Indicates the number of missing category images detected. |
| Processing Log | Shows real-time progress messages, including initialization, processing, and completion details. |
| Grid/Table Section | Displays the list of detected missing category images with details for review and action. |
| ID | Serial number for each missing image entry. |
| Missing Path | The expected directory path of the missing image file. |
| Image Name | The file name of the missing category image. |
| Source | Indicates which category the missing image belongs to (e.g., Default Category, Fitness Equipment). |
| Detected At | Timestamp showing when the missing image was identified. |
| Action (Upload Image) | Allows quick upload of the missing image directly from the grid. |
| Filters / Columns / Pagination | Options to filter results, adjust column visibility, and navigate through pages. |
Run this scan after catalog imports or media cleanups to ensure all category thumbnails and banner images display correctly on the storefront.
Thank you for choosing MageDelight!











