← Back to Blog

Finding and Removing Unused Media

Do not equate unattached media with unused media; build a multi-source audit and reversible cleanup process.

Veyra Admin

4 min read

  • Guide
  • Intermediate
  • 4 minutes read
  • Reviewed August 5, 2026
  • WordPress media

Removing unused files can reduce storage and clutter, but WordPress does not have one universal source of truth for media usage.

The Media Library's “unattached” filter is not a deletion list. Modern WordPress content can reference attachments without assigning a parent post.

Why Usage Is Difficult to Detect

Media references can exist in:

  • Block content.
  • Featured-image post meta.
  • Classic editor HTML.
  • Custom fields.
  • Theme options and Customizer data.
  • Navigation and widgets.
  • Patterns and templates.
  • CSS files.
  • Plugin tables.
  • Ecommerce galleries.
  • User profiles.
  • External websites and emails.
  • Direct public links.

A scanner that checks only post content will miss many of these.

Unattached Does Not Mean Unused

Attachment parentage reflects one relationship, often based on where the file was uploaded. It does not track every insertion.

An unattached logo may be used in the Site Editor. An attached image may no longer appear anywhere.

Build a Candidate List

Start with low-risk candidates:

  • Obvious duplicates.
  • Failed uploads.
  • Obsolete temporary exports.
  • Old generated derivatives not registered by the current system.
  • Assets from removed campaigns with documented expiry.

Record attachment ID, URL, file path, date, owner and reason for proposed deletion.

Search Multiple Systems

For each candidate:

  1. Search WordPress content and block markup.
  2. Check featured images and attachment IDs in post meta.
  3. Search custom fields and options.
  4. Review theme and plugin configuration.
  5. Check templates, patterns and CSS.
  6. Search web-server and CDN access logs where useful.
  7. Search external documentation, emails and known integrations.

No single check proves non-use, but combined evidence reduces risk.

Quarantine Before Deletion

For a large cleanup, use a reversible quarantine period:

  • Export the candidate list.
  • Back up files and database records.
  • Remove or redirect references.
  • Move or mark assets according to a tested process.
  • Monitor errors and requests.
  • Delete permanently only after review.

Do not move files manually if WordPress still expects them at the original path.

Generated Files

Orphaned sub-sizes can remain after theme changes or interrupted processing. Conversely, a filename that looks derivative may still be referenced directly.

Use attachment metadata and a purpose-built cleanup tool rather than deleting files based only on filename patterns.

Some assets must be retained for contracts, licences, records or audit history even when they are no longer public. Archive them outside public storage according to policy rather than deleting automatically.

Applying Finding and Removing Unused Media in a Real WordPress Project

Consider the source asset, WordPress attachment record, generated files and every public use of the media. Accessibility, licensing, storage, performance and deletion safety should be reviewed together.

A connected concept is Understanding the WordPress Media Library. Reading the two together helps separate the immediate task from the wider WordPress responsibility.

A useful implementation begins by writing down the current state, the intended outcome and the evidence that will prove the change worked. This prevents a configuration screen, plugin recommendation or code snippet from becoming the entire strategy.

A Reliable Workflow

  1. Define the outcome and the people affected.
  2. Inventory the current configuration, data and dependencies.
  3. Confirm a backup or rollback point.
  4. Rehearse the change on staging when production risk is meaningful.
  5. Apply one controlled change at a time.
  6. Validate the primary workflow and related functionality.
  7. Clear only the caches that are relevant.
  8. Record the final configuration, owner and next review date.

Validation Checklist

  • The intended WordPress object, setting or workflow changed.
  • Existing content and permissions still behave correctly.
  • Mobile, keyboard and authenticated states were tested where relevant.
  • Logs do not show new warnings or failed background work.
  • URLs, redirects and search signals remain consistent.
  • Another team member can understand the final state from the documentation.

Rollback and Documentation

A rollback is part of the procedure, not an admission of failure. Record which files, database state, settings and external services must return to the previous version. Document any data created between the change and rollback.

Follow the Complete Media Lifecycle

A media decision begins with the source file and continues through upload, attachment metadata, generated derivatives, delivery, reuse, replacement and deletion.

Review visual quality, accessibility text, licensing, dimensions, file weight, cache behaviour and every place the asset is referenced. WordPress can track an attachment record, but it cannot always identify every use created by themes, custom fields or external systems.

Plan the Cutover and the Rollback

Inventory files, database, DNS, certificates, email, cron, caches, webhooks and external credentials before moving traffic. Use serialization-aware URL replacement and preserve the old environment long enough to support rollback.

After cutover, test the complete path: old URL, redirect, final URL, canonical, sitemap, forms, login, scheduled tasks and external callbacks.

Official Reference Context

The WordPress Media Library Documentation is the primary version-specific reference for this topic. Use the current documentation to verify interface labels, supported APIs and behaviour before applying instructions to a production site.

How to Verify the Result

  • Check the original file, generated sizes and frontend delivery.
  • Verify alternative text, captions, credits and direct-file visibility.
  • Search for references before replacing or deleting the attachment.

Sources and Further Reading

Continue Learning