> For the complete documentation index, see [llms.txt](https://docs.momocode.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.momocode.de/en/shopware-6/media-cleanup-dashboard/1.-description.md).

# 1. Description

Unused media files accumulate in every Shopware store over time — especially after product imports, layout changes, or manufacturer logo updates. While Shopware includes the `media:delete-unused` CLI command, most merchants don't have server access to run it.

**Media Cleanup Dashboard** brings this functionality directly into the Shopware Administration: a visual dashboard that safely identifies, displays, and deletes unused files — no command-line access required.

![Start view with "Start scan" button](https://459847022-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LtiS3-dzuXFp_IH7yRw-1972196547%2Fuploads%2Fgit-blob-914196f1cd4f053cbf5cb9367caca8c1cc3973c2%2F1.png?alt=media)

## Features at a Glance

### Dashboard with File List

The dashboard displays all unused media files in a paginated list — with a preview thumbnail (or a file-type icon for PDFs, videos, etc.), file name, type, size, and upload date. A summary bar at the top shows the total file count and combined storage size at a glance.

### Async Background Scan

As of version 1.1 / 2.1, the scan runs asynchronously in the background via Shopware's message queue and is split into small batches — no HTTP timeout, even for very large media libraries. In the default setup, the Admin Worker processes the scan while the Administration is open; for large media libraries, we recommend a CLI worker (see **Installation → Background Processing of the Scan**). During the scan, the dashboard shows how many media have been checked and how many unused media have been found so far. If no worker processes the queue, a hint appears after 2 minutes; a scan without progress is stopped with an error message after 10 minutes and can be restarted. Results appear immediately once the scan completes. Results are cached for up to 4 hours: page navigation and delete operations never trigger a full re-scan. The **Rescan** button refreshes results on demand at any time.

![Result list with unused media files after the scan](https://459847022-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LtiS3-dzuXFp_IH7yRw-1972196547%2Fuploads%2Fgit-blob-b049306246ff59b72aa3732079318d11a863f690%2F2.png?alt=media)

### Bulk Selection and Safe Deletion

Select individual files via checkbox or use "Select all" — even across multiple pages. Before any deletion, a confirmation dialog shows the number of files and total size. A progress indicator is displayed during deletion; the result (deleted / skipped / failed) is reported in detail when complete.

In addition, the plugin performs a real-time last-mile verification immediately before every deletion — checking whether a file has been re-assigned since the scan — so no actively used files are ever deleted.

![Confirmation dialog before deleting](https://459847022-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LtiS3-dzuXFp_IH7yRw-1972196547%2Fuploads%2Fgit-blob-10c9316f83aafcbb4eca2a13587b6ed3a09f063a%2F3.png?alt=media)

### Filters and Sorting

Filter the list by file type (image, video, document, other), minimum file size, or upload age. Sort by file name, file size, or date — ascending or descending. A single click resets all active filters.

![File type filter "Image" applied](https://459847022-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LtiS3-dzuXFp_IH7yRw-1972196547%2Fuploads%2Fgit-blob-b311c1517f5e4af63827ddd177c3e45a27a9218e%2F4.png?alt=media)

### Include Media Linked to Past Orders (optional)

Shopware stores the product image on every ordered item — and keeps it even if the product is deleted later, so that old orders still show the image the customer bought. Such images therefore count as "in use" and do **not** appear in the list by default.

With the **Also include media linked to orders** checkbox next to the **Start scan** (or **Rescan**) button, the plugin also adds files to the scan that are only still linked this way:

* The option is **off** by default and applies to the **next** scan only. It is not saved and resets when you reopen the page.
* Affected files are marked **Only in orders** in the list, together with the number of linked orders. Files that are used elsewhere (e.g. in an active product, category, or layout) are still not shown.
* Before deletion, the confirmation dialog explicitly warns that the product image will no longer be displayed in those orders (e.g. order details, customer account). The orders themselves remain unchanged.

![Scan including order links, with the "Only in orders" label](https://459847022-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LtiS3-dzuXFp_IH7yRw-1972196547%2Fuploads%2Fgit-blob-b22a4ddb70c16492ab1f7037578edbe834b7e49f%2F5.png?alt=media)

### User Permissions (ACL)

The plugin adds two separate privileges:

* **momo\_media\_cleanup:read** — access to the dashboard and the unused media list
* **momo\_media\_cleanup:delete** — permission to delete unused media files

Staff can review the list without having delete access.

## Technical Details

| Property               | Value                                                                                                                                                                   |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Shopware compatibility | 6.6.x and 6.7.x                                                                                                                                                         |
| PHP                    | 8.2+                                                                                                                                                                    |
| External services      | None — the plugin communicates only with your own Shopware instance                                                                                                     |
| Database migrations    | None — the plugin does not create any custom tables                                                                                                                     |
| Background scan        | Async via Symfony Messenger in small batches — processed by the Admin Worker (while the Administration is open) or a CLI worker (recommended for large media libraries) |
