Add Custom Image Sizes in WordPress with add_image_size and Regenerate

This article is a localized edition of the Japanese original. Read the Japanese original

When you upload an image, WordPress automatically creates the resized copies set under Settings → Media, such as thumbnail, medium and large. With add_image_size() you can add your own sizes to that list. Use it when you need images with a fixed aspect ratio, such as card images on archive pages or OGP images.

The code and results in this article were checked in November 2026 on WordPress 7.1 (PHP 8.3, with Imagick as the image editor).

How to write add_image_size

add_image_size( $name, $width, $height, $crop );

Resize (false) vs. crop (true)

• false (resize only): scales the image down, keeping its aspect ratio, so that both width and height fit within the given values. A 2000×1500 image with 800, 0, false becomes 800×600.
• true (crop): creates an image of exactly the given width and height. Parts outside that aspect ratio are cut off around the center. A 2000×1500 image with 640, 360, true becomes 640×360.
• Array (crop position): like array( 'center', 'top' ), sets the horizontal anchor (left, center or right) and the vertical anchor (top, center or bottom). Useful, for example, when people's faces are near the top of the photo.

Register the sizes

Put the following code in your child theme's functions.php or in your own plugin file. Sizes are created at upload time, so it is natural to manage them together with the theme that uses the images.

<?php
add_action( 'after_setup_theme', function () {
	add_theme_support( 'post-thumbnails' );

	// For OGP and social sharing (crop to 1200x630)
	add_image_size( 'og-image', 1200, 630, true );

	// Cards on archive pages (crop to 16:9)
	add_image_size( 'card-16-9', 640, 360, true );

	// Square, cropped from the top (for photos with faces near the top)
	add_image_size( 'square-top', 400, 400, array( 'center', 'top' ) );

	// Resize to 800px wide, keeping the aspect ratio (0 = no limit)
	add_image_size( 'content-800', 800, 0, false );
} );

add_theme_support( 'post-thumbnails' ) enables featured images. You do not need it if your theme already turns them on.

With this code in place, uploading a 2000×1500 JPEG created og-image (1200×630), card-16-9 (640×360), square-top (400×400) and content-800 (800×600) in addition to the standard sizes.

Small originals are not enlarged

WordPress never enlarges images when it creates resized copies. Uploading a 500×300 image with the same settings gave the following:

• og-image (1200×630) and card-16-9 (640×360) were not created
• square-top (400×400) was created at 400×300, because the image was not tall enough

If a template asks for a size that was not created, the original image (500×300) is used as is. Where images must appear at a fixed size, upload images at least as large as the size, or make the display size consistent with CSS.

Use the sizes in templates

<?php
// Show the featured image at the card-16-9 size (inside the loop)
the_post_thumbnail( 'card-16-9' );

// Print an img tag from an attachment ID
$thumb_id = get_post_thumbnail_id();
echo wp_get_attachment_image( $thumb_id, 'card-16-9', false, array(
	'class' => 'card-image',
) );

// Get only the URL, width and height
$image = wp_get_attachment_image_src( $thumb_id, 'og-image' );
if ( $image ) {
	list( $url, $width, $height ) = $image;
	echo '<meta property="og:image" content="' . esc_url( $url ) . '">';
}

wp_get_attachment_image() and the_post_thumbnail() automatically add width and height attributes and a srcset attribute listing the other sizes with the same aspect ratio. WordPress also adds loading="lazy" automatically, so you normally do not need to set it.

The og:image example is only for reference. If an SEO plugin already outputs OGP tags, set the image in that plugin's settings so the tag is not output twice.

Add sizes to the block editor’s “Resolution” menu

Your sizes do not appear in the image block's settings by default. Give them names with the image_size_names_choose filter and they are added to the image block's "Resolution" options.

<?php
add_filter( 'image_size_names_choose', function ( $sizes ) {
	return array_merge( $sizes, array(
		'card-16-9'   => 'Card (640x360)',
		'content-800' => 'Content width (800px)',
	) );
} );

Only sizes that were actually created for that image can be chosen.

Stop creating sizes you do not use

Besides thumbnail, medium and large, WordPress creates medium_large (768px wide), 1536x1536 (1536px on the long side) and 2048x2048 (2048px on the long side) by default (the last two were added in WordPress 5.3). Removing unused sizes with the intermediate_image_sizes_advanced filter reduces upload processing and disk usage.

<?php
add_filter( 'intermediate_image_sizes_advanced', function ( $sizes ) {
	unset( $sizes['medium_large'] ); // 768px wide
	unset( $sizes['1536x1536'] );
	unset( $sizes['2048x2048'] );
	return $sizes;
} );

With this filter in place, uploading a 2000×1500 image did not create those three sizes. However, it also removes larger images that srcset could use for high-resolution screens. If your theme shows images wide, decide whether to keep them before removing them.

To cancel a size added by a theme or plugin, run remove_image_size( 'size-name' ) after that size has been registered.

Check the registered sizes

wp media image-size --format=table

This lists each size's name, width, height and crop (hard means crop, soft means resize). It shows registered sizes, so sizes you stopped creating with the filter above are still listed.

From PHP, wp_get_registered_image_subsizes() returns an array of size names with their width, height and crop.

Create the new sizes for existing images (regenerate)

Adding a size does not create it for images that are already uploaded. Rebuild them with WP-CLI's wp media regenerate. Take a backup first.

# Create only the missing sizes (existing files are kept)
wp media regenerate --only-missing --yes

# Rebuild one size only
wp media regenerate --image_size=card-16-9 --yes

# Rebuild specific attachment IDs (not post IDs)
wp media regenerate 123 124

Running wp media regenerate --yes without options deletes the old resized images before rebuilding them. Files for sizes you unregistered are deleted too, so if post content links directly to an image URL of that size, the image stops showing. If you do not want files deleted, add --skip-delete or use --only-missing as above.

On servers without WP-CLI, you can use a regeneration plugin such as "Regenerate Thumbnails".

Things to keep in mind

• Each extra size adds one more image file per upload. Register only the sizes your templates actually use.
• Size names are easier to work with if you avoid spaces and use letters, numbers and hyphens.
• If you switch themes, sizes registered in that theme's functions.php are no longer created for new uploads. Register sizes that should not depend on the theme in a plugin.

Related articles

• Responsive images (srcset) in WordPress
• What to do when images will not upload

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)