How WordPress generates image sizes

When you upload an image to WordPress, the original file is usually only the beginning.

WordPress can automatically create several additional versions of that image at different dimensions. Themes and plugins can register even more sizes, which means one Media Library attachment may correspond to many physical files inside the uploads directory.

For example, uploading:

mountain.jpg
2400 × 1600

might result in files such as:

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

A theme might also add:

mountain-600x400.jpg
mountain-1200x800.jpg

These generated files are commonly called image sub-sizes, intermediate image sizes or, less precisely, thumbnails.

Understanding how WordPress generates image sizes is important when building themes, optimizing storage, debugging responsive images, changing themes, regenerating thumbnails or figuring out why a particular image size does not exist.

This guide explains the complete WordPress image-size lifecycle, from registration and upload to resizing, cropping, metadata, large-image scaling and responsive image output.

What is a WordPress image size?

A WordPress image size is a named image configuration containing information such as:

• width;
• height;
• crop behavior.

A simple conceptual definition might be:

medium
width: 300
height: 300
crop: false

or:

homepage-card
width: 640
height: 420
crop: true

The name identifies the image size inside WordPress.

The dimensions and crop configuration tell WordPress how that size should be generated when an appropriate source image is processed.

WordPress has built-in image sizes

WordPress registers several image sizes by default.

Common examples include:

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

The exact configuration can depend on the current WordPress installation and Media settings.

You can inspect several standard dimensions under:

Settings
→
Media

These settings commonly control:

• Thumbnail size;
• Medium size;
• Large size.

Not every registered WordPress size is necessarily exposed on that settings screen.

Themes and plugins can register additional image sizes

WordPress provides:

add_image_size()

for registering custom sizes.

The official add_image_size() documentation describes the width, height and crop parameters supported by the API.

A basic custom size

add_image_size(
    'homepage-card',
    640,
    420,
    true
);

This creates a registration named:

homepage-card

with a target box of:

640 × 420

and cropping enabled.

A proportional size

add_image_size(
    'article-wide',
    1200,
    800,
    false
);

Here WordPress preserves the source aspect ratio while fitting the image within the configured limits.

Registered image size does not mean generated image file

This distinction is essential.

A site might currently register:

thumbnail
medium
medium_large
large
homepage-card
hero-large

but a particular attachment might contain only:

thumbnail
medium
homepage-card

Therefore:

registered image sizes
≠
generated sizes for every attachment

A size can be registered globally but absent for a specific image.

TheOneWP Image Sizes List is useful here because it can expose the sizes that actually exist for a specific Media Library image rather than simply showing the site’s global registrations.

How WordPress gets the registered image-size list

WordPress Core provides:

wp_get_registered_image_subsizes()

The official wp_get_registered_image_subsizes() documentation describes it as returning a normalized list of all currently registered image sub-sizes.

Conceptual result

array(
    'thumbnail' => array(
        'width'  => 150,
        'height' => 150,
        'crop'   => true,
    ),

    'medium' => array(
        'width'  => 300,
        'height' => 300,
        'crop'   => false,
    ),

    'homepage-card' => array(
        'width'  => 640,
        'height' => 420,
        'crop'   => true,
    ),
)

This gives WordPress a unified representation of image sizes introduced by:

• WordPress Core;
• the active theme;
• plugins;
• custom code.

The WordPress image generation lifecycle

The overall process can be simplified to:

image uploaded
↓
attachment created
↓
image inspected
↓
large-image scaling considered
↓
registered image sizes collected
↓
generation list filtered
↓
sub-sizes created
↓
attachment metadata updated
↓
files become available to WordPress

Several WordPress functions participate in this process.

wp_generate_attachment_metadata()

One of the central functions is:

wp_generate_attachment_metadata()

The official wp_generate_attachment_metadata() documentation describes it as generating attachment metadata and creating image sub-sizes for images.

For image attachments, the function works with WordPress’s image-processing system to generate the relevant metadata and derivatives.

Conceptually:

uploaded image
↓
wp_generate_attachment_metadata()
↓
image sub-size processing
↓
attachment metadata

wp_create_image_subsizes()

A more specialized part of the process is:

wp_create_image_subsizes()

The official wp_create_image_subsizes() documentation describes the function as creating image sub-sizes, adding the resulting information to the metadata sizes array and updating attachment metadata.

Its general workflow

The function begins by inspecting the source image.

Initial metadata can include:

width
height
file
filesize
sizes

WordPress can also read available EXIF or IPTC metadata from the image.

The initial:

sizes

array starts empty before the generated derivatives are added.

WordPress stores attachment metadata

Image-size generation is not only about files on disk.

WordPress also stores metadata describing those files.

You can retrieve it using:

wp_get_attachment_metadata()

A simplified image metadata structure might look like:

array(
    'width'  => 2400,
    'height' => 1600,
    'file'   => '2026/08/mountain.jpg',

    'sizes' => array(

        'thumbnail' => array(
            'file'   => 'mountain-150x150.jpg',
            'width'  => 150,
            'height' => 150,
        ),

        'medium' => array(
            'file'   => 'mountain-300x200.jpg',
            'width'  => 300,
            'height' => 200,
        ),
    ),
)

The exact metadata can contain additional information.

Why WordPress updates metadata while generating sizes

Modern WordPress image-generation logic is designed to preserve progress as individual sub-sizes are created.

This matters when processing large images or many derivatives.

Conceptually:

create size A
↓
record size A

create size B
↓
record size B

create size C
↓
record size C

If processing fails partway through, WordPress has a better chance of retaining information about successful earlier work instead of treating the entire operation as if nothing happened.

How WordPress decides which sizes to generate

After building the list of registered image sub-sizes, WordPress provides a filter named:

intermediate_image_sizes_advanced

This filter allows themes and plugins to alter the sizes that will actually be generated for an image.

Conceptually:

all registered sizes
↓
intermediate_image_sizes_advanced
↓
sizes selected for this upload
↓
generation

A plugin can remove an unnecessary size

For example, custom code could remove a specific derivative:

add_filter(
    'intermediate_image_sizes_advanced',
    function ( $sizes ) {

        unset(
            $sizes['unused-large']
        );

        return $sizes;
    }
);

This means that even if:

unused-large

is registered, it may not be generated for uploads while this filter is applied.

Why not every size is generated for every image

Finding fewer physical image files than registered sizes does not automatically mean WordPress failed.

There are several legitimate reasons a derivative can be absent.

The original image is too small

Suppose a site registers:

hero
1600 × 900

but you upload:

600 × 400

WordPress generally does not upscale that image to 1600 pixels simply because the size exists.

The larger derivative may therefore not be generated.

The requested dimensions do not require another physical file

Depending on source and target dimensions, WordPress may determine that creating another resized copy is unnecessary.

A filter removed the size

The generation list may have been changed before processing.

Image processing failed

Possible causes include:

• memory exhaustion;
• unsupported source data;
• corrupted files;
• GD or Imagick problems;
• filesystem failures.

The image predates the size registration

If:

image uploaded:
2023

homepage-card registered:
2026

the old attachment does not automatically gain the new derivative.

You may need Regenerating WordPress image thumbnails.

Soft resizing vs. hard cropping

The crop parameter changes how WordPress interprets the requested dimensions.

Soft proportional resizing

With:

crop = false

WordPress attempts to fit the image within the configured maximum dimensions while preserving its aspect ratio.

Suppose the source is:

1200 × 800

and the configured size is:

300 × 300
crop: false

The source aspect ratio is:

3:2

So the resulting image may be:

300 × 200

rather than:

300 × 300

Hard cropping

With:

crop = true

WordPress can crop the source to produce the requested aspect ratio.

The same source:

1200 × 800

with:

300 × 300
crop: true

can produce:

300 × 300

by removing some source content.

Crop position can also be controlled

add_image_size() can use more precise crop positioning.

For example:

add_image_size(
    'portrait-card',
    600,
    800,
    array(
        'center',
        'top'
    )
);

This tells WordPress to favor a particular crop position.

Crop positioning becomes particularly useful for:

• portraits;
• product imagery;
• hero compositions;
• editorial cards.

Image dimensions are not always the registered dimensions

This is a common source of confusion.

If WordPress registers:

medium
300 × 300
crop: false

you should not assume every medium image has dimensions:

300 × 300

The actual file can instead be:

300 × 200
200 × 300
300 × 169

depending on the source aspect ratio.

Registered dimensions describe the resize constraint.

Generated dimensions describe the actual output.

How generated image filenames work

Intermediate image filenames commonly contain the generated dimensions.

For example:

mountain.jpg

mountain-300x200.jpg

mountain-768x512.jpg

The pattern is usually:

original-name-WIDTHxHEIGHT.extension

However, application logic should not construct these filenames manually.

WordPress already stores their exact names in attachment metadata.

If you need a derivative URL, see Finding a specific WordPress image size’s URL.

Large-image scaling in WordPress

WordPress includes special handling for very large uploaded images.

The relevant filter is:

big_image_size_threshold

The default threshold is:

2560 pixels

If either width or height exceeds that threshold, WordPress can create a scaled version.

Example

Suppose you upload:

6000 × 4000

WordPress can create a scaled working image whose largest dimension is approximately:

2560px

while preserving the original upload separately.

The scaled image becomes important to WordPress

When the big-image system applies, the scaled image can become the attachment’s primary full-size representation for normal WordPress operations.

This is why manually removing:

-300x200

from a thumbnail filename is not a reliable way to determine the appropriate WordPress full-size URL.

Disabling or changing the large-image threshold

The threshold can be filtered.

For example, custom code can disable the scaling behavior:

add_filter(
    'big_image_size_threshold',
    '__return_false'
);

Or alter the threshold:

add_filter(
    'big_image_size_threshold',
    function () {
        return 4000;
    }
);

This should be changed deliberately.

Huge source images can consume significantly more:

• memory;
• processing time;
• storage;
• network bandwidth.

WordPress uses an image editor abstraction

WordPress does not generally implement every image operation directly itself.

It uses its image-editor abstraction to work with supported server image-processing libraries.

Common implementations include:

• Imagick;
• GD.

The image editor handles operations such as:

• loading the source;
• resizing;
• cropping;
• saving generated files.

Server capabilities affect results

Whether a particular image can be processed may depend on:

• the installed PHP extensions;
• supported file formats;
• available memory;
• server configuration.

WordPress 7.1 and client-side media processing

Modern WordPress also supports client-side media processing for supported uploads in appropriate environments.

This allows some image-processing work that traditionally happened entirely on the PHP server to occur in the browser during upload.

The architecture still revolves around familiar concepts such as:

• registered image sizes;
• big-image thresholds;
• missing image sizes;
• attachment metadata;
• WordPress filters controlling image generation.

For supported processing paths, information about image-size configuration can be exposed to the client so that the browser can produce the necessary media derivatives before or during the upload workflow.

Why this matters for developers

You should no longer assume that:

every image derivative
must always have been encoded
by a server-side WP_Image_Editor instance

The final WordPress concepts remain familiar, but some low-level hooks associated specifically with server-side editing may not run on the client-processing path.

When building advanced image-processing integrations, consult the current WordPress client-side media processing documentation.

The intermediate_image_sizes_advanced filter remains important

The image-size generation list can still be influenced through WordPress’s image-size filtering system.

This is important because plugins often do not need every registered derivative for every attachment.

For example:

product-specific sizes
might be unnecessary
for normal blog images

Strategically limiting generation can reduce unnecessary storage and processing.

How many image files can WordPress create?

Potentially quite a lot.

Suppose a site registers:

thumbnail
medium
medium_large
large
card-small
card-large
hero
product-grid
product-gallery

That is nine possible sub-sizes.

If:

10,000 images

are suitable for all nine sizes, you could theoretically have roughly:

90,000 derivative files

in addition to the originals.

Reality varies because not every size is generated for every source, but the multiplication effect is real.

Why unnecessary image sizes increase storage

Every generated derivative consumes:

• filesystem space;
• backup storage;
• potential object-storage space;
• inode/file-count capacity;
• processing time during upload.

A theme or plugin registering a single additional image size may seem insignificant.

Across a large media library, it can produce thousands of additional physical files.

Audit registered sizes periodically

Especially after:

• theme changes;
• plugin replacements;
• WooCommerce redesigns;
• page-builder migrations;
• years of site evolution.

TheOneWP Image Sizes List can help identify the native and custom image-size registrations currently active on the site.

Changing an image size does not rebuild old uploads

Suppose a theme originally registers:

homepage-card
400 × 300

and later changes it to:

homepage-card
640 × 420

Images uploaded after that change can use the new configuration.

Existing attachments still have derivatives generated under the old configuration unless they are regenerated.

The relationship is:

image-size registration
affects generation

it does not automatically
rewrite historical files

For the practical migration process, read Regenerating WordPress image thumbnails.

What happens during regeneration?

Thumbnail regeneration essentially asks WordPress to compare or rebuild image derivatives using the site’s current image-size definitions.

Conceptually:

existing attachment
+
current registered sizes
↓
reprocess source
↓
create current derivatives
↓
update metadata

The deeper internal behavior is covered separately in What happens when WordPress regenerates thumbnails.

Detecting missing image sub-sizes

WordPress provides:

wp_get_missing_image_subsizes()

This compares:

currently registered image sizes

against:

sizes stored in
attachment metadata

and returns the difference.

Conceptually:

registered

thumbnail
medium
large
homepage-card

metadata contains

thumbnail
medium

missing

large
homepage-card

Creating missing image sub-sizes

WordPress also provides:

wp_update_image_subsizes()

This can create currently registered image sub-sizes that are missing from an attachment and then update its image metadata.

This distinction is useful because rebuilding every derivative is not always necessary.

Sometimes the correct operation is simply:

generate what is missing

rather than:

rebuild everything

How to inspect a generated intermediate size

WordPress provides:

image_get_intermediate_size()

for inspecting a generated image representation.

Example:

$image = image_get_intermediate_size(
    123,
    'medium'
);

if ( $image ) {

    echo esc_url(
        $image['url']
    );

}

When a registered size name is supplied, the returned data can include:

• filename;
• width;
• height;
• path;
• URL.

This helps answer:

Did WordPress actually generate
this image size
for this attachment?

Image-size metadata and responsive images

Generated image sizes also support WordPress’s responsive-image system.

An image might be rendered with markup similar to:

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

The browser can then choose an appropriate image candidate rather than downloading the same large file for every viewport.

Image generation and responsive selection are separate stages

First:

WordPress generates
physical image files

Then:

WordPress can use metadata
to construct responsive markup

Finally:

the browser decides
which srcset candidate to download

WordPress does not directly choose the final responsive file downloaded by every browser.

Not every generated size appears in srcset

A Media Library attachment may have many physical derivatives.

A particular frontend srcset may use only some of them.

WordPress evaluates factors such as:

• aspect ratio compatibility;
• requested image dimensions;
• available attachment metadata;
• responsive-image calculations.

Therefore:

generated sizes
≠
every size included
in every srcset

Why themes should request named image sizes

When building a theme, requesting a registered size gives WordPress useful semantic information.

For example:

the_post_thumbnail(
    'homepage-card'
);

is usually preferable to manually constructing:

photo-640x420.jpg

because the named size participates in WordPress’s media APIs and metadata model.

How image size configuration affects design

Image sizes are not merely a technical optimization.

They encode design decisions.

A site might define:

avatar
1:1

blog-card
3:2

portfolio-card
4:3

hero
16:9

These different aspect ratios support specific presentation contexts.

Good image-size architecture therefore begins with:

actual layout requirements

rather than:

registering arbitrary dimensions
just in case

Avoid excessive near-duplicate sizes

Consider these registrations:

card-a
600 × 400

card-b
620 × 413

card-c
640 × 427

card-d
660 × 440

If the visual difference is negligible, generating all four may not be worthwhile.

Each additional size potentially multiplies:

• processing work;
• file count;
• disk usage;
• backup size.

Use meaningful breakpoints and layout requirements rather than creating a separate physical derivative for every minor CSS variation.

CSS resizing is not the same as WordPress image generation

This:

img {
    width: 300px;
}

does not create a 300-pixel image.

It only changes the rendered dimensions of the existing resource.

If the browser downloads:

2400px image

and CSS displays it at:

300px

the network cost of the larger file has already occurred.

Generated derivatives reduce transfer requirements

A correctly selected:

300px derivative

can be significantly smaller than the original.

This is one of the reasons WordPress’s image-size system exists.

Generated size does not guarantee that the frontend uses it

You can have the perfect:

640 × 420

card image stored on disk while the theme still requests:

full

If the frontend asks for the wrong size, generating more derivatives will not fix the template.

Debug the whole chain:

registered size
↓
generated file
↓
attachment metadata
↓
template request
↓
responsive markup
↓
browser request

Using TheOneWP Image Sizes List

TheOneWP Image Sizes List helps inspect WordPress image-size architecture without digging through theme and plugin code every time.

It can expose information such as:

• registered image-size names;
• configured dimensions;
• crop behavior;
• the component responsible for the registration;
• the sizes that actually exist for individual attachments.

This is especially useful when auditing sites that have changed:

• themes;
• page builders;
• e-commerce systems;
• media plugins;
• custom development teams.

Using TheOneWP Media Replace

Image generation also matters when an existing Media Library source file is replaced.

TheOneWP Media Replace can replace an existing image while preserving its attachment identity and regenerate relevant derivatives from the new source.

Without thumbnail regeneration, replacing only the original could leave an inconsistent combination such as:

new original
+
old thumbnail
+
old medium
+
old large

The relationship between replacement and re-uploading is covered in Replacing vs. re-uploading WordPress media.

Image optimization and image generation are different operations

Generating the correct dimensions does not necessarily mean the resulting file is optimally encoded.

Image optimization can involve:

• compression;
• quality settings;
• format conversion;
• metadata stripping;
• progressive encoding.

Image-size generation primarily answers:

What dimensions and crop
should this derivative have?

Optimization answers:

How efficiently can
that output be stored
and delivered?

TheOneWP Image Optimizer addresses the optimization side of the media workflow.

Image generation and caching are also separate

Creating a new image file does not necessarily invalidate every cached representation of an old one.

If a generated file receives a new filename:

photo-300x200.jpg

→

photo-640x420.jpg

the URL changes, which normally creates a different cache key.

If a media workflow replaces content behind an unchanged URL, browser and CDN caching becomes a separate issue.

See WordPress image cache-busting explained.

Common WordPress image-size generation mistakes

Assuming every registered size is physically generated

Check the attachment itself.

Assuming registered width and height equal actual output dimensions

Soft proportional resizing can produce different dimensions.

Registering too many similar image sizes

Every additional size can increase processing and storage.

Adding a new size and expecting old attachments to update

Historical media usually requires regeneration.

Manually constructing thumbnail filenames

Use WordPress attachment metadata and APIs.

Assuming CSS resizing saves bandwidth

CSS changes visual size, not the physical downloaded resource.

Assuming a generated image will automatically be used

The theme or block must request an appropriate size.

Ignoring crop behavior

A hard crop and proportional resize can produce dramatically different compositions.

Ignoring source dimensions

Small originals cannot satisfy every large registered size.

Ignoring large-image scaling

The WordPress full-size representation can differ from the untouched uploaded original.

Assuming all processing always happens on the PHP server

Modern WordPress supports client-side media-processing paths for supported images.

Deleting historical derivatives without checking references

An old file may still be referenced by stored content, external pages or cached markup.

WordPress image-size architecture checklist

• List the image sizes currently registered on the site.
• Identify which sizes come from WordPress Core.
• Identify which sizes come from the active theme.
• Identify plugin-generated sizes.
• Review configured width and height.
• Review crop behavior.
• Remove genuinely unnecessary custom registrations where safe.
• Avoid multiple near-identical image sizes without a design reason.
• Remember that registered dimensions can differ from actual generated dimensions.
• Check source dimensions before assuming a size should exist.
• Understand the big_image_size_threshold behavior.
• Use WordPress media APIs instead of manually constructing filenames.
• Inspect attachment metadata when debugging a specific image.
• Use image_get_intermediate_size() when checking an individual derivative.
• Use wp_get_missing_image_subsizes() when diagnosing missing sizes.
• Regenerate historical media after relevant size changes.
• Remember that generation and frontend selection are separate stages.
• Inspect src, srcset and sizes when debugging frontend output.
• Account for storage growth when registering additional sizes.
• Check server or client processing behavior when developing advanced media integrations.

Related WordPress image guides

Continue with these related guides and tools:

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

Final thoughts

WordPress image-size generation is best understood as a pipeline rather than as a collection of random thumbnail files.

The process starts with:

registered image-size definitions

and combines them with:

the uploaded image
+
its dimensions
+
crop rules
+
generation filters
+
the available image-processing system

to produce:

physical derivative files
+
attachment metadata

Those metadata records then allow WordPress themes, blocks and responsive-image functions to retrieve appropriate image representations later.

The central distinction remains:

registered size
≠
generated size
≠
frontend-selected size

A size can exist in the global registry without being generated for a particular attachment.

A derivative can exist for an attachment without appearing in every responsive srcset.

And a perfectly generated image file provides no performance benefit if the frontend continues requesting the full-size original.

Once you understand those separate stages, debugging WordPress media becomes much easier: inspect what is registered, inspect what was generated, inspect what the template requested and finally inspect what the browser actually downloaded.