SE Image Cleaner v1.7 — User Guide
1. Installation
Log in to your Joomla administrator panel and go to System > Install > Extensions. Upload the com_seimagecleaner_v1.7.zip file and click Install. Once installed, you will find SE Image Cleaner in the Components menu.
2. License Activation
SE Image Cleaner requires a valid license to operate. You only need to activate once — after that, the extension works permanently, even if your license later expires. An expired license only prevents you from downloading future updates.
Step 1: Open Options
From the SE Image Cleaner dashboard, click the "Options" button in the Joomla toolbar (top right), or click the "Open Options" button in the red license bar.
Step 2: Enter your details
In the License tab you will see two fields:
License Server URL — this is pre-filled with the default server address. You should not need to change it unless instructed otherwise.
License Key — paste your key in the format SS-XXXX-XXXX-XXXX-XXXX. This is provided in your purchase confirmation email.
Click Save & Close.
Step 3: Activate
Back on the dashboard, click the "Activate License" button. The component will contact the license server to validate your key. If successful, the bar turns green and you are ready to go.
License status colours
Green — license is active. Everything works, updates are available.
Amber — license has expired. The extension still works fully, but you will not receive updates until you renew. After renewing, click "Check License" to refresh.
Red — license has not been activated yet. Follow the steps above.
The "Check License" button can be used at any time to re-validate your license against the server. This is useful after renewing an expired license.
3. Disclaimer
The first time you access SE Image Cleaner after installation (or after clearing your session), you will see a disclaimer screen. Read it carefully, tick the checkbox to confirm you have a working backup, and click "Accept & Continue". This screen appears once per session as a safety reminder.
Important: Always ensure you have a full backup of your website before deleting any images. Use your hosting provider's backup tools or a component like Akeeba Backup.
4. The Dashboard
The dashboard is your starting point. From here you can:
Run a scan (two modes available), access the Trash Bin, access the Safe List, view the license status bar, and open Options via the toolbar.
5. Running a Scan
There are two scan modes:
Scan Core Tables
Scans your /images/ directory and checks references against a curated list of known Joomla core and popular third-party extension tables. This includes Joomla content, categories, modules, menus, tags, SP Page Builder, K2, EasyBlog, VirtueMart, Kunena, JCE, and more. This is the recommended mode for most sites and runs quickly.
Scan All Database Tables
Scans every text column in every table in your entire database. This catches references in obscure or custom extensions that the core scan might miss, but takes longer. Recommended for sites with many third-party extensions or custom components. You will be asked to confirm before starting.
How the scan works
The scan runs in four phases, each as a separate AJAX request so there are no timeout issues:
Phase 1 — Scans your /images/ directory and counts all image files (jpg, jpeg, png, gif, webp, svg, bmp, ico, avif).
Phase 2 — Discovers which database tables need scanning and how many there are.
Phase 3 — Processes each database table one at a time, extracting image path references. A live progress bar shows which table is being scanned and how far through the list you are. The log panel shows which tables contained image references and how many were found.
Phase 4 — Cross-references the image files from Phase 1 against the references found in Phase 3. Any image not referenced anywhere is flagged as an orphan.
When complete, you are automatically redirected to the results page.
If a table causes an error during scanning (for example, a very large log table), the scan will retry once and then skip that table and continue. A warning message at the end will tell you how many tables were skipped. Certain known large tables that never contain image data (such as session logs, AcyMailing history, and search index tables) are automatically skipped to save time.
6. Scan Results
The results page shows all orphaned images found by the scan.
At the top, three summary cards show the total number of orphans found, their combined file size, and which scan mode was used.
Each orphan is listed with a thumbnail preview, filename, directory path, file size, and last modified date. You can click any thumbnail to see a larger preview.
Filtering and sorting
Use the search box to filter results by filename or path. Use the sort dropdown to order by size (largest/smallest first), name (A-Z/Z-A), or date (newest/oldest first). Use the per-page dropdown to show 20, 50, 100, or 200 results per page.
Actions
Select images using the checkboxes (or use Select All / Select None), then choose an action:
Mark as Safe — adds the selected images to the safe list so they are excluded from all future scans. Use this for images you know are referenced in template files, CSS, or external systems.
Move to Trash — moves images to a special trash folder inside /images/. The original files are preserved and can be restored later. This is the recommended first step.
Delete Permanently — removes the files from disk immediately. This cannot be undone.
You can also use the corresponding buttons in the Joomla toolbar at the top of the page.
7. The Trash Bin
Access the Trash Bin from the dashboard sidebar.
Images moved to trash are stored in /images/_seimagecleaner_trash/ with their original directory structure preserved. Each trashed image has a metadata sidecar file recording its original path and the date it was trashed.
From the Trash Bin you can:
Restore — moves selected images back to their original locations on disk.
Delete Permanently — removes selected images from the trash folder forever.
8. The Safe List
Access the Safe List from the dashboard sidebar.
The safe list is for images that appear as orphans in scan results but you know are actually in use — for example, images referenced in template PHP files, CSS background images, or images used by external systems. Marking them as safe means they will be automatically skipped in all future scans.
From the scan results page, select the images and click "Mark as Safe".
From the Safe List management page, you can see all safe-listed images with their preview, path, file size, the date they were added, and whether the file still exists on disk. Select images and click "Remove from Safe List" if you want them to appear in scan results again.
The safe list is stored as a JSON file at /images/_seimagecleaner_safelist.json.
9. Joomla Updates
SE Image Cleaner supports Joomla's built-in update system. When a new version is available, it will appear in your Joomla update manager (System > Update > Extensions).
Downloads require a valid (non-expired) license. Your license key is automatically sent with update requests via Joomla's download ID system. If your license has expired, you will need to renew it before you can download new versions. After renewing, click "Check License" on the SE Image Cleaner dashboard to refresh your status.
10. Important Notes and Limitations
What the scan checks
The scan checks image references stored in your Joomla database. This covers article content, categories, modules, menu parameters, custom fields, tags, template styles, and many popular third-party extensions.
What the scan does not check
The scan cannot detect images referenced only in template PHP files, CSS/SCSS files, JavaScript files, hardcoded HTML outside the database, or external systems. If an image is used in one of these ways, it will appear as an orphan. Use the safe list feature to protect these images.
Supported image formats
jpg, jpeg, png, gif, webp, svg, bmp, ico, avif.
Scan scope
Only files inside the /images/ directory are scanned. Images stored in other locations (such as /media/ or custom folders) are not included.
File permissions
The component needs write permission to the /images/ directory to move files to trash, create the safe list file, and store the license activation file. If you encounter permission errors, check that your web server user has write access to /images/ and to the component's admin folder.
System files
Certain files are always excluded from scan results: index.html, web.config, .htaccess, joomla_black.png, and powered_by.png.
11. Troubleshooting
"License has not been activated yet"
Go to Options, check that the License Key is entered correctly, save, then click "Activate License" on the dashboard.
"Could not connect to the license server"
Check that the License Server URL is correct and that your server can make outbound HTTP requests. Some hosting environments block outgoing connections — contact your host if needed.
"License validated but could not write activation file"
The component's admin folder does not have write permission. Check that the web server user can write to administrator/components/com_seimagecleaner/.
Scan stalls or shows "skipped" warnings
Some very large database tables may be too big to scan within PHP's limits. The scan automatically retries once and then skips problematic tables. Known large tables (session logs, AcyMailing history, search indexes) are pre-skipped. If you see many skipped tables, try increasing PHP's memory_limit and max_execution_time in your hosting configuration.
"Form::loadForm could not load file" when opening Options
This indicates the config.xml file was not installed correctly. Reinstall the component using the latest zip file.
Images I know are used appear as orphans
These images are likely referenced in template files, CSS, or JavaScript rather than in the database. Mark them as safe so they are excluded from future scans.
The scan found zero orphans
Your /images/ directory is clean, or all images are referenced in the database. If you expected to find orphans, try running a "Scan All Database Tables" scan to ensure the widest possible search, then check whether the images you expected might be stored outside the /images/ directory.
12. Uninstalling
Go to System > Manage > Extensions, find SE Image Cleaner in the list, and click Uninstall. This removes the component files and configuration. It does not modify your /images/ directory.
Note: If you have images in the trash folder (/images/_seimagecleaner_trash/), the safe list file (/images/_seimagecleaner_safelist.json), or the license activation file, these are stored inside /images/ and the component admin folder respectively. They will not be automatically removed during uninstallation. You can safely delete them manually if you no longer need them.
