Regenerating WordPress image thumbnails

Regenerating WordPress image thumbnails means creating new intermediate image files for media that is already present in the Media Library, using the image sizes currently registered by WordPress, your active theme and your plugins.

This is useful after changing themes, adding a new custom image size, modifying thumbnail dimensions, repairing missing image files or updating the way a website displays responsive images.

When WordPress receives a new image upload, it normally creates several smaller versions automatically. A single original image may therefore produce files such as:

photo.jpg
photo-150x150.jpg
photo-300x200.jpg
photo-768x512.jpg
photo-1024x683.jpg

The exact files depend on the image dimensions and the image sizes registered on the site.

The important detail is that changing those registered sizes later does not automatically rebuild every image that was uploaded in the past.

That is where thumbnail regeneration becomes necessary.

This guide explains when to regenerate WordPress thumbnails, what files WordPress creates, how to use WP-CLI, how to regenerate only missing sizes, what happens to old files, how responsive images are affected and what to check before and after running a large regeneration.

What are WordPress image thumbnails?

In WordPress terminology, a thumbnail is not necessarily only the tiny square image called thumbnail.

WordPress commonly uses the term image sub-size or intermediate image size for resized versions generated from an uploaded image.

Standard installations commonly register sizes such as:

• thumbnail;
• medium;
• medium_large;
• large.

The exact dimensions can depend on your WordPress settings and current version.

Themes and plugins can register additional image sizes.

A theme can add custom sizes

For example:

add_image_size(
    'homepage-card',
    600,
    400,
    true
);

This registers an image size called:

homepage-card

with dimensions:

600 × 400

and hard cropping enabled.

The official add_image_size() documentation covers custom size registration.

Why WordPress creates several versions of one image

Serving every image at its original resolution would be inefficient.

Imagine uploading:

6000 × 4000
8 MB

and then displaying it inside a:

300px-wide blog card

The browser would receive far more image data than the layout requires.

WordPress solves much of this by creating multiple dimensions when the image enters the Media Library.

A browser or theme can then use an appropriately sized file.

Responsive images use these generated files

WordPress has native responsive-image support and can generate markup containing:

srcset

and:

sizes

attributes.

For example:

<img
    src="photo-768x512.jpg"
    srcset="
        photo-300x200.jpg 300w,
        photo-768x512.jpg 768w,
        photo-1024x683.jpg 1024w
    "
    sizes="(max-width: 768px) 100vw, 768px"
    alt=""
>

The browser can then choose a suitable candidate according to layout and device characteristics.

The official WordPress Responsive Images documentation explains how WordPress builds this responsive markup.

When do you need to regenerate WordPress thumbnails?

You usually need regeneration when the site’s current image-size definitions no longer match files generated for older uploads.

After changing your WordPress theme

A new theme may register different image sizes.

For example, your old theme may have used:

blog-card
400 × 300

while the new theme expects:

blog-card
720 × 480

Images uploaded after activating the new theme can receive the new dimensions automatically.

Older Media Library images cannot magically travel back through time and regenerate themselves.

They may therefore lack the size required by the new theme.

After adding a new custom image size

If you add:

add_image_size(
    'product-hero',
    1200,
    800,
    true
);

existing attachments will not necessarily have:

product-hero

files.

New uploads will.

Regeneration creates the newly registered size for older suitable images.

After changing Media settings

WordPress image dimensions can be configured under:

Settings
→
Media

If you change a standard size from:

300 × 300

to:

400 × 400

existing files generated with the old dimensions remain unchanged until they are regenerated or otherwise replaced.

After changing crop behavior

Image sizes can use:

• proportional resizing;
• hard cropping.

Changing:

crop: false

to:

crop: true

changes the visual result even if the nominal width and height are similar.

After a migration or incomplete uploads transfer

Sometimes the database migrates correctly while part of:

wp-content/uploads/

does not.

If original image files exist but generated thumbnails are missing, regeneration may recreate the missing intermediate files.

After restoring an incomplete backup

The same issue can occur if a backup includes originals but omits some derivative image files.

What thumbnail regeneration actually uses

WordPress needs the original or appropriate source image plus the site’s currently registered image-size configuration.

Conceptually:

source image
+
registered image sizes
↓
image editor
↓
new sub-size files
↓
attachment metadata updated

The Core function:

wp_generate_attachment_metadata()

is part of the system responsible for generating attachment metadata and image sub-sizes.

The official wp_generate_attachment_metadata() documentation shows that the function works with currently registered image sub-sizes.

Where WordPress stores image size information

There are two separate layers to understand.

The files

Generated image files normally live beside the uploaded image inside:

wp-content/uploads/YYYY/MM/

For example:

mountain.jpg
mountain-150x150.jpg
mountain-300x200.jpg
mountain-768x512.jpg

The attachment metadata

WordPress also stores information about generated sizes in attachment metadata.

Conceptually, that metadata can contain:

width
height
file
sizes
image_meta

and inside the sizes array:

thumbnail
medium
large
custom sizes

Each generated entry can include information such as:

• filename;
• width;
• height;
• MIME type;
• file size.

Regenerating thumbnails does not mean re-uploading images

This distinction matters.

Regeneration typically keeps the existing attachment record.

That means the attachment can retain:

• attachment ID;
• title;
• caption;
• description;
• alt text;
• taxonomy relationships;
• references from content.

You are rebuilding derivative files associated with the existing attachment, not creating an entirely new Media Library item.

This is very different from deleting an image and uploading another copy.

See Replacing vs. re-uploading WordPress media for that distinction.

How to see which image sizes WordPress currently registers

Before regenerating thousands of files, it helps to understand what sizes the site actually wants.

WP-CLI provides:

wp media image-size

This can return a table similar to:

+--------------+-------+--------+------+
| name         | width | height | crop |
+--------------+-------+--------+------+
| thumbnail    | 150   | 150    | hard |
| medium       | 300   | 300    | soft |
| medium_large | 768   | 0      | soft |
| large        | 1024  | 1024   | soft |
+--------------+-------+--------+------+

The exact list can be considerably larger on a complex site.

The command is documented in the official WP-CLI media documentation.

You can also use TheOneWP Image Sizes List to inspect image-size information directly from the WordPress media interface.

Regenerating thumbnails with WP-CLI

WP-CLI provides one of the cleanest methods for large or development-oriented WordPress installations.

The main command is:

wp media regenerate

The official wp media regenerate documentation covers attachment targeting, missing sizes and cleanup options.

Regenerate all images

wp media regenerate

WP-CLI asks for confirmation when appropriate.

To answer automatically:

wp media regenerate --yes

Regenerate specific attachments

If you know the attachment IDs:

wp media regenerate 123 124 125

This is much safer when testing a new image-size configuration.

Regenerate a specific image size

You can target one registered size:

wp media regenerate \
    --image_size=large

This avoids rebuilding every derivative when only one image size changed.

Generate only missing image sizes

If the correct files already exist for most attachments, recreating everything can be unnecessary.

WP-CLI supports:

wp media regenerate \
    --only-missing

This is particularly useful when:

• a new size was recently registered;
• a migration lost some thumbnails;
• a previous regeneration stopped partway through;
• only certain attachments are missing derivatives.

WordPress Core can detect missing sub-sizes

Core also has functionality that compares the sizes stored in attachment metadata with currently registered image sizes.

The relevant system includes:

wp_get_missing_image_subsizes()

and:

wp_update_image_subsizes()

The latter can create image sub-sizes that are currently registered but missing from an attachment.

Not every registered size can be generated for every image

This is an important source of confusion.

If WordPress registers:

hero
1600 × 900

and the original upload is:

600 × 400

WordPress generally does not invent a larger 1600-pixel image simply to satisfy the registered size.

That means a size may legitimately be absent for a particular attachment.

Missing does not always mean broken

If a regeneration tool reports that a requested size was not created, first compare:

• original dimensions;
• requested dimensions;
• crop behavior;
• supported image format;
• available image editor.

This is one reason Image Sizes List can be useful when confirming which files actually exist for a specific attachment.

What happens to old thumbnail files?

This is where thumbnail regeneration becomes less obvious.

There may be three different things on disk:

current registered sizes
+
old registered sizes
+
historical files no longer referenced

Changing your theme or image-size definitions does not inherently guarantee that every obsolete file from every previous configuration disappears.

Old image sizes can accumulate

Imagine the site used:

theme-a-card
400 × 300

for three years.

You switch themes, which registers:

theme-b-card
640 × 480

New or regenerated metadata may now reference the new size, while old physical files can still remain in the uploads directory depending on the regeneration method and cleanup options.

Do not delete files blindly

An apparently obsolete thumbnail could still be referenced by:

• hardcoded HTML;
• old post content;
• external websites;
• cached markup;
• email templates;
• custom database fields.

A file no longer registered by WordPress is not automatically safe to erase.

WP-CLI cleanup options

The WP-CLI regeneration command provides options specifically related to old thumbnail files.

–skip-delete

You can use:

wp media regenerate \
    --skip-delete

to skip deletion of original thumbnail files during regeneration.

This can be useful when old image URLs may still be referenced from places outside your control.

–delete-unknown

WP-CLI also supports:

wp media regenerate \
    --delete-unknown

for deleting thumbnails belonging to old image sizes that are no longer registered.

This is a cleanup operation and deserves more caution than ordinary regeneration.

Back up before destructive cleanup

Before deleting historical derivatives on a production site, preserve:

• database;
• uploads directory;
• current configuration.

Regenerating missing files is generally reversible.

Deleting unknown historical files is not as forgiving when somebody later discovers that a seven-year-old newsletter linked directly to one of them.

Regeneration after changing themes

Theme changes are probably the most common practical regeneration scenario.

Before the switch

Your Media Library may contain:

image.jpg
image-theme-a-card.jpg
image-theme-a-hero.jpg

After activating the new theme

The new theme may expect:

theme-b-card
theme-b-featured
theme-b-hero

New uploads receive those sizes.

Old uploads do not automatically receive them.

After regeneration

The image can now have:

image.jpg
image-theme-b-card.jpg
image-theme-b-featured.jpg
image-theme-b-hero.jpg

while some older Theme A derivatives may still exist physically depending on your cleanup strategy.

Regeneration after adding WooCommerce or another plugin

Plugins can also register image sizes.

Installing a plugin that displays existing Media Library images may introduce new requirements for:

• product cards;
• galleries;
• member avatars;
• portfolio items;
• custom post layouts.

If those image sizes are newly registered, older images may need regeneration before every component receives the intended files.

Always confirm the plugin’s own media architecture before running a site-wide regeneration solely because a new size appears.

Regeneration and responsive srcset

Responsive image markup depends partly on available image metadata.

If an attachment gains a newly generated intermediate size, WordPress may then have another valid source candidate to consider when building srcset.

Conceptually:

before regeneration

300w
768w
1024w

could become:

300w
600w
768w
1024w

after a new 600-pixel image size becomes available.

Regeneration does not automatically rewrite every stored HTML fragment

WordPress can generate responsive markup dynamically in many contexts, but websites can also contain:

• hardcoded image URLs;
• page-builder data;
• custom fields;
• cached HTML;
• external references.

Do not assume regeneration alone repairs every historical reference.

Regeneration and image URLs

Generated thumbnail filenames usually encode their dimensions.

For example:

photo-300x200.jpg

If the newly generated file instead becomes:

photo-400x267.jpg

that is a different URL.

This generally avoids browser-cache confusion because the resource address changed.

But some image workflows reuse URLs

Replacing an image file in place may create a different caching problem because browsers or CDNs can continue serving an old response for an unchanged URL.

That topic is covered in WordPress image cache-busting explained.

CDN considerations after regenerating thumbnails

If the site uses a CDN, the newly generated files must eventually become available through the CDN’s delivery layer.

For new URLs, this is usually straightforward:

browser requests new thumbnail
↓
CDN misses
↓
CDN fetches origin
↓
CDN caches result

Deleted old thumbnails may remain cached

If you remove an old derivative from the origin, a CDN may still temporarily serve a cached copy until its cache entry expires or is purged.

Do not confuse regeneration with CDN invalidation

They are different operations.

thumbnail regeneration
=
origin file generation

CDN purge
=
edge cache invalidation

For a broader explanation of asset delivery layers, read CDN vs. self-hosted assets in WordPress.

Large Media Libraries need a careful strategy

Regenerating ten images is trivial.

Regenerating:

150,000 attachments
×
8 registered sizes

is not.

A large regeneration can involve:

• CPU usage;
• disk I/O;
• PHP memory;
• image-processing libraries;
• storage growth;
• long execution time;
• backup growth;
• CDN traffic.

Prefer command-line processing for large batches

Browser-based regeneration tools depend on web requests and can run into:

• PHP execution limits;
• reverse-proxy timeouts;
• browser interruptions;
• AJAX failures.

WP-CLI is usually easier to supervise for large server-side jobs.

Test on a small sample first

Before:

wp media regenerate --yes

try:

wp media regenerate 123 124 125

and inspect the results.

Check server storage before regeneration

Every new derivative consumes disk space.

Suppose:

20,000 original images

and a new theme introduces:

4 new image sizes

Theoretical additional file count could approach:

80,000 files

although not every size will necessarily be generated for every image.

Storage impact is often underestimated

Review:

• current uploads size;
• available disk space;
• backup storage;
• object-storage limits;
• inode/file-count limits where applicable.

Creating ten nearly identical custom image sizes because each designer wanted a 12-pixel difference is one of those small architectural decisions that eventually becomes somebody else’s storage invoice.

Check the available WordPress image editor

WordPress relies on image-processing support available in the server environment.

Common implementations include:

• Imagick;
• GD.

If the server cannot process a particular image correctly, regeneration may fail.

Possible symptoms include

• missing derivatives;
• memory exhaustion;
• unsupported image-format errors;
• processing failures for very large originals.

Do not immediately blame the regeneration command if the underlying image editor cannot open or save the source file.

Large images and WordPress scaling

WordPress includes special handling for very large uploaded images.

The current image-subsizes code applies a:

big_image_size_threshold

filter, with a default threshold of:

2560 pixels

for width or height.

When applicable, WordPress can create a scaled version that becomes the working full-size attachment image while preserving information about the original upload.

This matters during regeneration

The attachment’s current original/source relationship can affect which file WordPress uses to create derivatives.

Do not assume every attachment’s visible “full” image is necessarily the untouched file originally uploaded by the user.

Why regeneration can appear to do nothing

Sometimes a regeneration succeeds but produces no obvious new file.

The requested size already exists

If the correct derivative exists and metadata already describes it, there may be nothing useful to change.

The source image is too small

A requested larger size may not be appropriate to generate.

The size is no longer registered

If your code that calls:

add_image_size()

is not active during regeneration, WordPress cannot create that size from thin air.

A filter removed the size

WordPress exposes filters that can alter the list of sub-sizes generated for a particular image.

One relevant filter is:

intermediate_image_sizes_advanced

Plugins can use this to suppress unnecessary image sizes.

The image editor failed

Inspect logs and command output rather than assuming success from the absence of a browser error.

How to confirm regeneration worked

Do not judge only by whether the command reached:

Success

at the end.

Check the actual files

Verify that expected derivatives exist in:

wp-content/uploads/...

Check attachment metadata

Confirm that the size appears in the attachment’s generated metadata.

Check the Media Library

Open the attachment and inspect its available image sizes.

TheOneWP Image Sizes List is particularly relevant here because it can expose generated size information for individual images.

Check the frontend

Inspect the resulting HTML and Network panel.

Verify that WordPress is actually requesting the expected image URL.

Check responsive markup

Look at:

src
srcset
sizes

rather than checking only the visibly rendered resolution.

Using TheOneWP Media Replace and thumbnail regeneration

TheOneWP Media Replace provides a different but related workflow.

Instead of deleting an existing Media Library attachment and uploading another one, the module can replace the file while preserving the attachment relationship.

For image replacements, the module regenerates the relevant thumbnails so derivative files reflect the new source image.

This matters because replacing only the original file without rebuilding derivatives could leave:

new original
+
old thumbnail
+
old medium
+
old large

which would create inconsistent output across different layouts.

Regenerating thumbnails vs. replacing media

These operations solve different problems.

Regenerate thumbnails when

• the original image is correct;
• image-size definitions changed;
• some derivatives are missing;
• a new theme needs additional sizes.

Replace media when

• the source image itself is wrong;
• you need a newer version of the same asset;
• you want to preserve the attachment and its references.

The relationship is:

regeneration
=
same source
new derivatives

replacement
=
new source
same attachment identity

Regeneration and backups

Before a large production regeneration, create a backup.

At minimum, protect:

• database;
• uploads directory.

The database matters because attachment metadata can change.

The uploads directory matters because physical derivative files can be created, overwritten or removed depending on the tool and options used.

Backups matter even more before cleanup

Generating missing files is usually low risk.

Using options that delete unknown or historical sizes carries a higher risk of breaking old references.

A safe regeneration workflow

Step 1: identify why regeneration is needed

Do not regenerate simply because a plugin presents a shiny button labelled “Regenerate”.

Determine whether:

• the theme changed;
• a new size was added;
• dimensions changed;
• files are missing;
• media was restored incompletely.

Step 2: list registered image sizes

wp media image-size

Step 3: inspect several existing attachments

Compare their generated sizes against the currently registered list.

Step 4: check available storage

Estimate the possible increase in files and disk space.

Step 5: back up the site

Protect database and media files.

Step 6: regenerate a small sample

wp media regenerate 123 124 125

Step 7: inspect the output

Check dimensions, crops, filenames and frontend display.

Step 8: run the required batch

If you only need missing files:

wp media regenerate \
    --only-missing

If everything must be rebuilt:

wp media regenerate --yes

Step 9: clear relevant caches if necessary

This can include:

• page cache;
• object cache where relevant;
• CDN cache;
• browser cache during testing.

Step 10: verify frontend responsive images

Inspect actual output on several templates and viewport sizes.

Common thumbnail regeneration mistakes

Regenerating without knowing which sizes are registered

List the current image-size configuration first.

Expecting old uploads to automatically gain a newly registered size

New size definitions generally affect future generation until existing images are regenerated.

Assuming every size should exist for every image

Source dimensions can prevent particular derivatives from being generated.

Deleting old thumbnails immediately

Old URLs may still be referenced somewhere.

Regenerating thousands of images through one fragile browser request

Use a robust batch process or WP-CLI for large libraries.

Ignoring disk space

Every additional image size can multiply storage requirements.

Forgetting backups before destructive cleanup

A directory full of supposedly useless thumbnails becomes surprisingly important five minutes after deletion.

Assuming regeneration changes the attachment ID

Normal thumbnail regeneration works with the existing attachment.

Expecting regeneration to fix a bad original

If the source image itself is wrong, replace or edit the source.

Ignoring CDN caches

File generation and cache invalidation are separate processes.

Checking only the visible image

Inspect srcset, metadata and network requests too.

Running a full regeneration when only one size is missing

Use targeted regeneration when possible.

WordPress thumbnail regeneration checklist

• Confirm why regeneration is required.
• List currently registered image sizes.
• Check which theme and plugins register custom sizes.
• Review crop settings.
• Inspect source image dimensions.
• Understand that not every size can exist for every image.
• Back up the database.
• Back up the uploads directory.
• Check available server storage.
• Test several attachment IDs first.
• Use WP-CLI for large media libraries where practical.
• Use --only-missing when you only need absent derivatives.
• Use --image_size when only one size needs rebuilding.
• Use cleanup options carefully.
• Do not assume obsolete files are safe to delete.
• Check attachment metadata after regeneration.
• Check generated files on disk.
• Verify frontend output.
• Inspect responsive srcset.
• Clear relevant page or CDN caches when required.
• Verify important templates on desktop and mobile.

Related WordPress media guides

Continue with these related guides and tools:

• What happens when WordPress regenerates thumbnails
• How WordPress generates image sizes
• Finding a specific WordPress image size’s URL
• What happens when WordPress regenerates thumbnails
• Replacing vs. re-uploading WordPress media
• WordPress image cache-busting explained
• What happens when WordPress regenerates thumbnails
• Organizing a large WordPress Media Library
• Keeping a WordPress Media Library organized at scale
• Image Sizes List
• Media Replace

Final thoughts

Regenerating WordPress image thumbnails is fundamentally a synchronization process.

You are bringing:

existing Media Library images

into alignment with:

the image sizes
your site currently registers

The basic workflow is:

original image
+
current image-size definitions
↓
generate missing or replacement sub-sizes
↓
update attachment metadata
↓
WordPress can use those files
in templates and responsive markup

Regeneration is especially useful after theme changes, new custom image sizes, migrations and incomplete media restores.

But regeneration and cleanup should not be confused.

Creating the new files your website currently needs is one task.

Deleting every old thumbnail that appears obsolete is another, more destructive task that requires additional verification.

Before processing a large Media Library, inspect your registered image sizes, test a few attachments, verify available storage and create a backup.

For large sites, WP-CLI gives you precise control over the process, including the ability to regenerate individual attachments, a single image size or only missing derivatives.

After the operation, verify the real files, attachment metadata, frontend markup and responsive image sources rather than assuming that a successful command automatically means every template is now using the intended image.