How to Clean Up Your WordPress Media Library Safely (2026)

For developers: WP-CLI and SQL

# Count Media Library items
wp post list --post_type=attachment --format=count

# List the image sizes registered by the current theme and plugins
wp media image-size

# Regenerate only missing sizes (skips sizes that already exist)
wp media regenerate --only-missing --yes

# Export attachment IDs, file paths and dates for review
wp post list --post_type=attachment --fields=ID,post_title,post_date,guid --format=csv > media.csv

A safer SQL starting point

SELECT a.ID, a.post_title
FROM wp_posts a
JOIN wp_postmeta f ON f.post_id = a.ID AND f.meta_key = '_wp_attached_file'
WHERE a.post_type = 'attachment'
  AND NOT EXISTS (
    SELECT 1 FROM wp_posts p
    WHERE p.post_type NOT IN ('attachment','revision')
      AND ( p.post_content LIKE CONCAT('%', SUBSTRING_INDEX(SUBSTRING_INDEX(SUBSTRING_INDEX(SUBSTRING_INDEX(f.meta_value,'/',-1),'.',1),'-scaled',1),'-rotated',1), '%')
         OR p.post_content LIKE CONCAT('%wp-image-', a.ID, '"%') )
  )
  AND NOT EXISTS (
    SELECT 1 FROM wp_postmeta m
    WHERE m.meta_key = '_thumbnail_id' AND m.meta_value = a.ID
  );

Deeper cleanup: orphan files, image sizes, CSS images, PDFs and videos

The steps above are enough for most sites. Older sites, migrated sites and large stores usually need a few extra checks. Every command in this section only reads data unless it says otherwise. Run anything that removes files on staging first, after a backup.

Find files on disk that are not in the Media Library

WordPress has no built-in report for orphan files, so compare two lists: every file the Media Library knows about, and every file in your uploads folder. The first command builds the known list. It includes each attachment’s main file, its generated sizes, the original of any image WordPress scaled down, and the backup copies the image editor keeps.

wp eval '
foreach ( get_posts( array( "post_type" => "attachment", "post_status" => "any", "numberposts" => -1, "fields" => "ids" ) ) as $id ) {
  $file = get_attached_file( $id );
  if ( ! $file ) { continue; }
  $dir = dirname( $file );
  echo $file, "\n";
  $meta = wp_get_attachment_metadata( $id );
  foreach ( $meta["sizes"] ?? array() as $size ) { echo $dir, "/", $size["file"], "\n"; }
  if ( ! empty( $meta["original_image"] ) ) { echo $dir, "/", $meta["original_image"], "\n"; }
  $backups = get_post_meta( $id, "_wp_attachment_backup_sizes", true );
  if ( is_array( $backups ) ) { foreach ( $backups as $b ) { if ( ! empty( $b["file"] ) ) { echo $dir, "/", $b["file"], "\n"; } } }
}' | LC_ALL=C sort -u > known-files.txt

find "$(wp eval 'echo wp_get_upload_dir()["basedir"];')" -type f | LC_ALL=C sort > disk-files.txt

# Files on disk that no attachment claims
LC_ALL=C comm -13 known-files.txt disk-files.txt > not-in-library.txt

Treat not-in-library.txt as a review list, not a delete list. It will include folders that plugins write into uploads (caches, form uploads, backups, Elementor’s generated CSS) and the index.php or .htaccess files that protect them. Leave those alone. What remains is usually left over from migrations, FTP uploads and attachments deleted without their sizes. Move those files to a folder outside uploads instead of deleting them, check your site for a week or two, then remove them. If your media is offloaded to S3 or another storage service, this disk comparison does not apply.

Image sizes and the “-scaled” copy

Core WordPress can create six sizes from each image: thumbnail (150 px), medium (300 px), medium_large (768 px), large (1024 px), 1536×1536 and 2048×2048. Themes and plugins add their own. Since WordPress 5.3, an image wider or taller than 2,560 px is also scaled down to a copy such as photo-scaled.jpg, which becomes the “full” size, while the original stays on disk. One large photo can easily become eight or more files.

# Sizes registered right now (core, theme and plugins)
wp media image-size

# Delete files for sizes that are no longer registered (removes files).
# Try one attachment ID first, then all images. Needs WP-CLI 2.11 or later.
wp media regenerate 123 --delete-unknown
wp media regenerate --delete-unknown --yes

Before you remove an old size, search your post content for its dimensions. Posts written in the classic editor often link straight to a file such as photo-640x480.jpg, and that image breaks once the size is gone. Be careful with plain wp media regenerate too: by default it deletes the existing thumbnails before it creates new ones, so if a size’s dimensions have changed, links to the old file names break. Add --skip-delete to keep the old files, or use --only-missing. Never delete the original that sits next to a -scaled file. WordPress makes the other sizes from it.

Build your whitelist before you trash anything

Every scanner has blind spots, so decide what must never be removed and exclude it first. In Media Purge, click Keep to add a file to the Whitelist, or whitelist many files at once with a bulk action. Usual candidates:

• Images named in theme CSS, Additional CSS or template files (see the next section).
• Files linked from menus, emails, newsletters, ads or other websites.
• Images loaded by plugins the scanner doesn’t read, such as sliders, popups and form builders.
• On WooCommerce stores, variation images, category thumbnails and the placeholder image, which Media Purge’s readme does not list. See how to delete unused WooCommerce product images safely.

Find images used in CSS

A CSS background image is a URL inside a stylesheet, not an attachment ID, so many scanners can’t link it to a Media Library item. Check three places. First, theme and child-theme files:

grep -rhoE "wp-content/uploads/[^\"') ]+" wp-content/themes/ | sort -u

Second, the Customizer’s Additional CSS, which WordPress saves as a custom_css post. Third, plugin and theme settings stored in wp_options. Both queries below are SELECTs and change nothing:

wp db query "SELECT ID, post_title FROM wp_posts WHERE post_type = 'custom_css' AND post_content LIKE '%wp-content/uploads%'"
wp db query "SELECT option_name FROM wp_options WHERE option_value LIKE '%wp-content/uploads%'"

Some plugins save settings as JSON with escaped slashes, so treat the results as a partial list. Page builders are a separate case: Media Purge reads Elementor background images from Elementor’s data, but CSS typed into a custom CSS box is still plain text. More on that in how to remove unused images in Elementor.

PDFs, videos and audio

Non-image files are often the largest items in a library, and they are linked in ways a scan rarely sees: menu links, download buttons, emails and other sites. Export them for review, and check which custom menu links point at uploads:

wp post list --post_type=attachment --post_mime_type=application/pdf --fields=ID,post_title,guid --format=csv > pdfs.csv
wp post list --post_type=attachment --post_mime_type=video --fields=ID,post_title,guid --format=csv > videos.csv

wp db query "SELECT post_id, meta_value FROM wp_postmeta WHERE meta_key = '_menu_item_url' AND meta_value LIKE '%wp-content/uploads%'"

Before you remove a large PDF or video, look for recent requests to its URL in your analytics or server logs. A file nothing on your site links to can still be downloaded every day from an old email or a partner’s page. In Media Purge, you can filter unused media by file type and see storage split into images, videos, audio and documents, so you can start with the biggest files.

CDN caches can hide broken images

A CDN can keep serving a deleted image from its cache, so a missing file may not show up as broken until the cache expires. Cloudflare, for example, caches a 200 response for 120 minutes by default when your server sends no cache headers, and image files often get much longer cache times. Purge the CDN before you test. If you restore a file, purge its URL again, because CDNs can cache the 404 as well (3 minutes by default on Cloudflare).