Delete Unattached Media in WordPress

Learn about the "Uploaded to" information, how to attach and detach images and posts, and the reliability when it comes to deleting unused media.

Users regularly ask me why the “Uploaded to” information in the WordPress media library differs from the information that Image Source Control shows before one can delete unattached media.

The short answer is that WordPress only saves the “Uploaded to” information when you upload an image directly into the post editor. This is in contrast to Image Source Control, which constantly looks at where the image is actually in use.

For this post, I dug deep into the WordPress core to find out how “Uploaded to” technically works and which limitations it comes with when you want to delete unattached media.

Main takeaways:

  • The “Uploaded to” information is only written when a media file is uploaded via the post editor.
  • WordPress will not update that information neither when removing the file nor when adding it somewhere else.
  • You can manually attach and detach images to posts via the List view in the Media Library.
  • Use Image Source Control to identify media usage and delete unused images.

“Uploaded to” from a technical side.

Some users confuse the “Uploaded to” information in WordPress with something like “Used in” and think it will help them identify attached and unattached images. As you will see below, this is far from reality. WordPress core developers didn’t even intend this information to identify unattached media.

All the information about who uploaded an image, when, and where is stored in an entry for the attachment in the wp_posts table.

These are the appropriate fields:

  • Uploaded to => post_parent
  • Uploaded by => post_author
  • Uploaded on => post_date

It makes sense that only one author could upload a specific image on a particular date into an individual post. Confusing this is only a problem if WordPress users think that the “Uploaded to” information is updated, and they can use it to identify where an image is actually embedded.

WordPress attaches images to posts in the wp_media_attach_action() function in wp-admin/includes/media.php. WordPress also uses this function to detach or “unattach” images and posts, meaning to remove the value from the post_parent field.

I’ve looked through all the WordPress core and could only find usages of the post_parent field for attachments when displaying “Uploaded to” in the backend. I guess it would be possible to show that information on a dedicated attachment page in the frontend, but core doesn’t seem to do this.

The issue with (un)attached images

Images become attached to posts when you upload them via the post editor, e.g., by using the Image or any other media block or dragging and dropping an image into the post.

When you upload an image directly into the media library and then add that image to a post, it will not be attached to that post, i.e., it will not show “Uploaded to.”

If you remove an attached image from a post, the “Uploaded to“ information is not updated either and will still show that post even if you continue using that image in another post or page.

In contrast, Image Source Control builds a reliable image-post index for actual image usage in the frontend.

The plugin needs such an index for its core features: delete unused images and show image captions.

You can review the index in the Tools section of the plugin.

Attach and detach images from posts

WordPress allows you to manually detach an image from a post. This option is only available in the List view of the media library.

Go to Media > Library. Find the List view icon at the top left. You should find the “Uploaded to” column in the list with links to attach or detach images.

Click the “Detach” link in the “Uploaded to” column to remove the relationship between an image and a post. This action will be performed immediately.

You can also manually attach an unattached image using the appropriate link. I’d bet that 99% of WordPress users never clicked on it or know what comes next:

Showing the modal in the media library that lists all posts that can be attached to a given image.
Choose a post to attach an image.

Should you delete unattached media based on this?

There is an argument for keeping an updated list of where you use each image if you want to delete unused images at any given stage.

However, using the WordPress core features for this reaches its limits when you use the same image in multiple posts or outside of the post content.

It would be best if you were confident that you would never forget to update that information and keep other authors vigilant about this feature.

I personally couldn’t do this, so I extended Image Source Control to automatically keep a list of unattached images that I can review anytime at my convenience.

Special case: Cropped images

I stumbled upon an interesting behavior while looking through the code that attaches and detaches images to posts. It is not affecting my work, but I want to mention it anyway since it is not the first time that cropped images have unexpected side effects when it comes to either keeping or removing information from the original image.

When cropping an image through the media library, the newly generated image replaces the old entry.

The old one is still used in the post, though.

The new cropped image, now technically not used in the post, shows the “Uploaded to” entry on the media page in the backend anyway.

Conclusion

After 15 years of working with WordPress, I have used the “attach” feature for the first time while writing this post. I have also never seen anyone else making use of it.

I can finally give a deeper explanation to customers asking about “Uploaded to.” As the label says, it is only a snapshot of when somebody uploaded an image. The information will not be updated when you attach images to or detach them from a post and can, therefore, not be used to delete unused images.

FAQ

What is unattached media in WordPress?

Unattached media is technically any file you upload directly to the WordPress Media Library and not through the post editor. WordPress doesn’t monitor where that media is actually in use.

Where can I detach media?

The only non-technical way is through the List view in the Media Library. Go to Media > Library > List, then look for the “Uploaded to” column.

Portrait of Thomas Maier, founder and CEO of Image Source Control

Questions? Feedback? How can I help?