Auto-Compress WordPress Images on Upload: Quality, Max Size, WebP

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

When you upload an image, WordPress uses the server's image library (Imagick or GD) to create thumbnails and the other image sizes. These images are saved compressed, and you can change their quality with filters. Without any plugin, a few lines in functions.php let you adjust the file size of the generated images.

The filters and default values in this article were checked against the WordPress core source code (6.9).

What WordPress does on upload

The original uploaded file is kept as is. The quality settings apply to the images WordPress creates (each size, -scaled, and rotated images).

Default quality

Quality is a number from 1 to 100. Lower values give smaller files and rougher images.

Change the quality

The wp_editor_set_quality filter

wp_editor_set_quality applies to every format. Its second argument is the format being saved (the MIME type), so you can set a different quality per format.

<?php
// functions.php
add_filter( 'wp_editor_set_quality', function ( $quality, $mime_type ) {
	if ( 'image/jpeg' === $mime_type ) {
		return 75;
	}
	if ( 'image/webp' === $mime_type ) {
		return 80;
	}
	return $quality;
}, 10, 2 );

The jpeg_quality filter

jpeg_quality applies to JPEG only. WordPress applies jpeg_quality after wp_editor_set_quality, so if you use both, JPEGs get the jpeg_quality value.

<?php
add_filter( 'jpeg_quality', function () {
	return 75;
} );

One of the two is enough. Use wp_editor_set_quality if you want different values per format.

If you lower the quality too far, artifacts show up around text and at color edges. After changing the value, upload the same photo and compare file size and appearance before settling on it.

Scale down large images automatically (big_image_size_threshold)

For images wider or taller than 2560px, such as smartphone photos, WordPress by default creates a -scaled file reduced to 2560px and uses that on your pages. You can change this limit with the big_image_size_threshold filter.

<?php
// Set the limit to 1920px
add_filter( 'big_image_size_threshold', function () {
	return 1920;
} );

<?php
// Do not scale down (use the original size)
add_filter( 'big_image_size_threshold', '__return_false' );

Even when an image is scaled down, the original upload stays on the server. To save disk space, you need to make images smaller before uploading them.

Save as WebP (image_editor_output_format)

The image_editor_output_format filter changes the format of the images WordPress creates. In this example, when you upload a JPEG, the generated images are saved as WebP.

<?php
add_filter( 'image_editor_output_format', function ( $formats ) {
	$formats['image/jpeg'] = 'image/webp';
	return $formats;
} );

• If the server's Imagick or GD does not support WebP, nothing is converted.
• Since WordPress 6.7, this filter's default value already maps HEIC images to JPEG. Add to the array as in the example above so you do not wipe out the existing entries.
• The original JPEG file stays on the server.

Detailed steps for WebP conversion and when to use a plugin instead are covered in How to convert images to WebP in WordPress.

Check the server’s image processing

You can check with WP-CLI which library WordPress uses and which formats it can save.

# The image editor class in use (WP_Image_Editor_Imagick or WP_Image_Editor_GD)
wp eval 'echo _wp_image_editor_choose() . PHP_EOL;'

# Whether WebP can be saved (bool(true) means yes)
wp eval 'var_dump( wp_image_editor_supports( array( "mime_type" => "image/webp" ) ) );'

In the admin, the Info tab of Tools > Site Health shows the ImageMagick and GD versions and the formats they support.

Apply the settings to existing images

The filters only affect images created after you add them. To apply them to images already uploaded, regenerate the image sizes.

# Regenerate all sizes for all images (no confirmation prompt)
wp media regenerate --yes

# Only specific images (give attachment IDs)
wp media regenerate 123 456

• With many images this takes time and puts load on the server. Run it when traffic is low.
• Back up wp-content/uploads before running it.
• If you cannot use WP-CLI, you can regenerate with a plugin instead, as explained in How to use Regenerate Thumbnails.

Things to watch out for

• The quality filters do not compress the original uploaded file itself. To shrink the original too, compress it before uploading or use an image optimization plugin that also compresses originals.
• Camera data (EXIF) is removed only from images created by Imagick or GD. The original file keeps it. If you do not want to publish location data and the like, remove it before uploading.
• Using an image optimization plugin together with the filters in this article can compress images twice and degrade quality. Decide which one does the compression.

Summary

• The default quality of images WordPress creates on upload is 82 for JPEG and others, and 86 for WebP
• Use wp_editor_set_quality for per-format values and jpeg_quality for JPEG only (if both are set, jpeg_quality wins for JPEG)
• Change the 2560px scale-down limit with big_image_size_threshold
• Save as WebP with image_editor_output_format, and apply changes to existing images with wp media regenerate

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