Filter Hook since 5.3.0

big_image_size_threshold

Filters the pixel threshold for scaling down large uploads

Description

big_image_size_threshold controls whether an oversized upload gets scaled down to a 'large' version before WordPress builds the rest of its size set — directly affects storage use and upload processing time.

When it runs

Runs during image processing in wp_generate_attachment_metadata(), before intermediate sizes are generated.

Signature

apply_filters( 'big_image_size_threshold', int $threshold, array $imagesize, string $file, int $attachment_id );

Parameters

threshold int — The threshold value in pixels, default 2560.
imagesize array — Indexed array of the original image's width and height.
file string — Full path to the uploaded file.
attachment_id int — The attachment post ID.

Examples

Basic

add_filter( 'big_image_size_threshold', function( $threshold ) {
    return 1920;
} );

Lower the scale-down threshold to 1920px.

Real case

add_filter( 'big_image_size_threshold', function( $threshold, $imagesize ) {
    return ( $imagesize[0] > $imagesize[1] ) ? 2560 : 1600;
}, 10, 2 );

Use a different threshold for landscape vs portrait uploads.

Edge case

add_filter( 'big_image_size_threshold', '__return_false' );

Disable the auto-scaling behavior entirely, keeping full-resolution originals.

Common Use Cases

Reduce storage use from oversized uploads
Speed up media processing on large images
Tune the threshold per site's actual display needs
Disable auto-scaling for sites that need full-resolution originals

Common mistakes

Disabling this on a site with frequent huge uploads without also addressing PHP memory/time limits — processing very large originals can still time out

Related hooks

related wp_generate_attachment_metadata

FAQ

What’s the default threshold?

2560 pixels on the long edge, introduced in WordPress 5.3.

Does lowering this threshold affect already-uploaded images?

No — it only affects images processed after the filter is added; existing attachments aren't retroactively rescaled.

Source: wp-admin/includes/image.php

Group wizard

One session: this hook, then each related_hooks entry. Walk it and tell us what to change.

big_image_size_threshold → wp_generate_attachment_metadata

functions.php — big_image_size_threshold

functions.php

<?php
/**
 * Practice: hook into big_image_size_threshold
 */
add_filter( 'big_image_size_threshold', function( $threshold, $imagesize, $file, $attachment_id ) {
	// Write your callback here. Always return the value.

	return $threshold;
} );

Group tour

big_image_size_threshold · Hook 1 of 2 · Step 1 of 6

Meet big_image_size_threshold

Filters the pixel threshold for scaling down large uploads

type filterphase mediasince 5.3.0source wp-admin/includes/image.php

apply_filters( 'big_image_size_threshold', int $threshold, array $imagesize, string $file, int $attachment_id );

add_filter( 'big_image_size_threshold', function( $threshold ) {
    return 1920;
} );

PHP big_image_size_threshold · Hook 1 of 2 · Step 1 of 6

Practice the big_image_size_threshold WordPress filter hook in our interactive sandbox — a VS Code-style editor with a step-by-step big_image_size_threshold tutorial, add_filter exercises, and instant feedback. No local WordPress install required.