Strapi 5 plugin unused media

Find, review and safely clean up the media files nobody uses anymore.

⚠️ For Strapi 5 only. This plugin targets Strapi ^5.0.0. It is not compatible with Strapi v4.

🚀 Overview

The Media Library grows forever — old uploads, abandoned drafts, replaced images. Strapi has no built-in way to tell which files are actually still used.

Unused Media scans your whole project, cross-references every file against all your content (entries, components, dynamic zones) and lists the ones referenced nowhere, with a preview, their size and the total storage you can reclaim.

It also handles the tricky part most tools miss: media embedded inside rich-text and Blocks fields (which create no relation in Strapi) — so you never delete an image that's actually shown in a body of text.

✨ Features

• 🔎 Accurate unused detection across entries, components and dynamic zones (via the polymorphic relation table).
• 📊 Storage gauge — total library size vs. reclaimable space.
• 🖼️ Native Media Library look — grid & list views, real previews, the same cards you already know.
• 🗑️ Bulk delete through the upload service (removes the file, its thumbnails and formats).
• 🙈 Ignore-list — keep a file (or a whole folder) out of the results, with a Show ignored toggle and one-click restore.
• 🛡️ Deep scan — searches rich-text / Blocks / text content for each file's hash to catch "soft" references no relation can see.
• ✅ Deletion safety net — a file referenced in content is never deleted, even by mistake.
• 🔐 Role-based permissions (read / delete / manage ignore-list) with support for the is creator condition.
• 🌍 i18n — English & French included.

⏳ Installation

With npm:

npm install strapi-plugin-unused-media

With yarn:

yarn add strapi-plugin-unused-media

Then rebuild the admin panel:

npm run build && npm run develop

✨ Getting Started

The plugin is enabled by default once installed. To configure it, add it to config/plugins.ts (or config/plugins.js):

export default ({ env }) => ({
  "unused-media": {
    enabled: true,
    config: {
      // Folder ids whose files are never considered unused.
      excludedFolderIds: [],
      // MIME types never flagged. A trailing "*" is a wildcard, e.g. "video/*".
      excludedMimeTypes: [],
      // Only flag files uploaded more than N days ago (0 = no age filter).
      minimumAgeInDays: 0,
      // Set to false to make the plugin strictly read-only.
      allowDelete: true,
    },
  },
});

Permissions

Open Settings → Administration Panel → Roles and grant, per role, under the Unused media group:

Each action also supports the WHEN is creator condition, so an editor can be limited to the media they uploaded.

Deep scan & the "soft reference" blind spot

Media inserted in a richtext (markdown) or blocks field is stored inline (by url/hash) and creates no relation in Strapi. A plain scan would flag such a file as unused.

Click Deep scan to additionally search every text / rich-text / Blocks column for each candidate's hash. Files found in content are marked Referenced, locked and protected from deletion. The same check always runs as a safety net at deletion time.

🎉 Result

The dashboard, with the storage gauge, the native-style cards and the toolbar (grid/list, Show ignored, Deep scan):

The role permissions, with the three actions and the is creator condition:

🐛 Bugs

Found a bug or have a feature request? Please open an issue on the GitHub repository.

License

MIT © Paul Richez