WordPress can automatically reduce images that are too large when they are uploaded. For such a file, it creates a copy with the `-scaled` suffix, and this version is usually used as the primary image in the attachment metadata.
This reduces the load on the website and speeds up image processing, but it is not always suitable for photographs used in print, zoom galleries, product catalogs, or on Retina displays. You can adjust the scaling threshold with a WordPress filter or disable automatic scaling completely when necessary.
What WordPress Does with a Large Image
When an image is uploaded, WordPress checks the dimensions of the raster file. If its longest side exceeds the configured threshold, WordPress creates a smaller version and adds the `-scaled` suffix to the filename. For example, `photo.jpg` may result in `photo-scaled.jpg`.
The scaled version becomes the primary file in the attachment metadata. As a result, a user or site template may receive not the file that was originally uploaded, but its smaller copy. The original file often remains in the file system, but WordPress no longer uses it as the primary source for that attachment.
Scaling takes place before or during the creation of derivative sizes, including thumbnails, medium images, and other versions generated by the theme or plugins.
- the file size delivered by the website is reduced;
- the time required for the browser to process the image is shortened;
- the risk of excessive server load while generating derivative sizes is reduced;
- some detail may be lost if the image is needed for printing, cropping, or enlargement.
When to Keep Automatic Scaling Enabled
For most content websites, limiting image dimensions is a useful feature. Cameras and smartphones can produce photographs with very high resolutions, even though those images may be displayed in a relatively small area on the website. In most cases, there is no practical need to store and process such a large original for every page.
An automatic threshold is especially useful for blogs, news websites, corporate pages, and projects where images are viewed only on screens. It helps prevent accidental uploads of files that consume significant storage and force PHP to spend more time generating thumbnails.
However, scaling is not a replacement for image optimization. It changes the dimensions but does not necessarily compress JPEG, PNG, or WebP files optimally. Full control may also require the right format, compression settings, and responsive image delivery.
- keep the limit if editors regularly upload photos from smartphones or cameras;
- check the maximum width requirements of your theme, gallery, and plugins;
- do not focus only on resolution: format, compression quality, and the number of derivative files also matter.
How to Change the Scaling Threshold with an MU Plugin
A must-use plugin, or MU plugin, is a convenient way to control the threshold. It loads automatically and does not depend on the regular plugin activation controls in the dashboard.
Create the `wp-content/mu-plugins` directory if it does not already exist. Then create a file inside it, such as `image-threshold.php`, and add the following filter:
- the value is specified in pixels;
- WordPress compares it with the longest side of the image, whether that is the width or height;
- the filter affects new uploads and does not automatically change existing files.
<?php
add_filter( 'big_image_size_threshold', function ( $threshold ) {
return 3000; // максимальна сторона у пікселях
} );
How to Choose a Value
A threshold of 3000 pixels means that an image with a width or height greater than 3000 pixels may be scaled. This does not mean that every image will be forcibly enlarged or resized to 3000 pixels: smaller files will not be scaled in this way.
The value should match the actual content width, catalog requirements, and intended use cases. A website with large banners or detailed product photography may need a higher threshold than a standard blog.
- do not set the threshold too low if images need to be cropped or enlarged;
- do not set it extremely high without checking available storage and processing time;
- after changing the value, upload a test file that is guaranteed to exceed the new threshold.
How to Disable Automatic Scaling Completely
If the website must preserve uploaded images at their original dimensions, the filter can return `false`. This disables automatic scaling for large images:
- the original dimensions will be available to WordPress as the primary file for a new attachment;
- derivative sizes may still be created by the theme or plugins;
- disabling scaling does not compress or optimize files that have already been uploaded.
<?php
add_filter( 'big_image_size_threshold', '__return_false' );
When Disabling Scaling Makes Sense
This option may be appropriate for stock photography websites, photographers’ portfolios, professional galleries, print-related projects, or stores where visitors need to inspect product details.
For a standard website, completely disabling the feature without additional limits can create more problems than it solves. Large files consume storage, take longer to process, and may increase server load during bulk media imports.
- make sure the server has sufficient disk space;
- check PHP memory limits and the capabilities of the image processing library;
- agree on acceptable image dimensions and file formats with the content editors.
What Changes After Installing the Filter
The filter is applied while a new upload is being processed. If you change the threshold today, WordPress will not automatically regenerate images that were uploaded previously or remove existing files with the `-scaled` suffix.
For existing media files, you must separately decide whether derivative sizes need to be regenerated. You can use the tools or plugins already used on the site for thumbnail regeneration, but create a backup before performing a bulk operation and test the result on a copy of the website.
Do not immediately delete `-scaled` files manually after changing the setting. Database records, caches, or page content may still reference them. First determine which files are actually being used.
- check the new file in the Media Library and on the page where it is displayed;
- inspect the image URL: it can show whether the `-scaled` version is being used;
- make sure the gallery, zoom feature, and lightbox use the required version;
- verify your backups before bulk regeneration or cleanup.
Common Mistakes and Post-Configuration Checks
The most common mistake is editing theme files instead of using an MU plugin. Theme updates or theme changes can cause that code to be lost. Another issue is misunderstanding the threshold: it applies to the longest side, not the image area and not just its width.
You should also account for caching. If a page or CDN has stored an older version of the image, the changes may not be visible immediately. For testing, use a new filename, clear the relevant cache, and view the image in a cache-free session.
If the MU plugin does not work, check the file path, PHP syntax, permissions, and error logs. WordPress usually loads PHP files in the `mu-plugins` directory automatically without additional activation.
- upload an image that exceeds the configured threshold;
- check whether a file with the `-scaled` suffix exists;
- compare the actual dimensions of the original with those of the file used by the attachment;
- open the image on the frontend, in the gallery, and in the full-size view;
- check storage usage and processing time after changing the setting.
Frequently asked questions
Does WordPress delete the original image after creating a `-scaled` file?
Not necessarily. The scaled copy becomes the primary file in the attachment metadata, while the original may remain on disk. Do not delete it manually until you have checked the media file's references and usage.
Does `big_image_size_threshold` affect images that have already been uploaded?
No. The filter is applied during a new upload or a separate reprocessing operation. Existing files are not regenerated automatically.
Will the `-scaled` suffix disappear if I increase the threshold?
For new files that do not exceed the new threshold, a scaled version will not be created. Existing files with the `-scaled` suffix will not be renamed or deleted automatically.
Is disabling scaling enough for a high-quality gallery?
No. You must also check compression quality, formats, responsive image sizes, gallery settings, and zoom functionality. Disabling the threshold only preserves the large file as the primary version.
Conclusion
Automatic scaling of large images in WordPress is not an error but a compromise between quality, speed, and resource usage. For most websites, it is better to keep a controlled threshold than to disable the feature unconditionally.
If your business use case requires full-size originals, change `big_image_size_threshold` through an MU plugin, test new uploads, and plan separately for storage, backups, and regeneration of existing media files.