Oversized image files: the 200KB and 1MB thresholds
One unoptimised photo can outweigh every other asset on the page. squirrel measures the images the crawl fetched and reports the heavy ones.
What an oversized image is
Images are usually the largest thing a page downloads. A camera JPEG straight out of a phone is several megabytes; the same picture, resized to the width it is displayed at and encoded as WebP, is often under 100 KB with no visible difference.
Weight shows up directly in Largest Contentful Paint, because the LCP element is an image on most content pages, and it costs the visitor real bandwidth. squirrel’s default thresholds are 200 KB for a warning and 1 MB for a failure.
What squirrel checks
The rule is site-wide and reads the image sizes the crawl fetched. It emits up to two checks:
- Pass when the crawl recorded no image resources at all. Message:
No image files detected. A recorded resource whose size could not be read falls through to the pass below instead. image-file-sizefails for files aboveerror_bytes, 1 MB by default. Message:2 image(s) exceed 1.0 MB, each listed with its URL, size, status and content type, and the pages it appears on. Severity error, weight 7.image-file-size-warnwarns for files abovewarn_bytesand at or below the error threshold. Message:9 image(s) exceed 200.0 KB.image-file-sizepasses when neither fired. Message:All image files are within size limits.
Only images the crawl actually fetched are measured, so an image loaded by script after render does not appear.
How to fix it
cwebp -q 80 photo.jpg -o photo.webpResize to the largest dimension the image is displayed at, then encode as WebP or AVIF at a quality around 75 to 85. An image CDN does both on request, which is usually less work than a build step.
Serving several sizes with srcset is what stops a phone downloading the desktop file. Compression alone does not fix that.
| Rule ID | images/image-file-size |
| Category | Images |
| Scope | Site-wide |
| Severity | error |
| Weight | 7/10 |
Options
| Option | Type | Default | Description |
|---|---|---|---|
warn_bytes | number | 204800 | Byte size to trigger warning |
error_bytes | number | 1048576 | Byte size to trigger error |
Configuration example
[rule_options."images/image-file-size"]
warn_bytes = 102400
error_bytes = 512000Enable / disable
Disable this rule
[rules]
disable = ["images/image-file-size"]Disable all Images rules
[rules]
disable = ["images/*"]Enable only this rule
[rules]
enable = ["images/image-file-size"]enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.
Related rules
- images/modern-format: the format change that usually fixes the size.
- images/srcset: serving a smaller file to smaller screens.
- images/responsive-size: thumbnail-sized images whose files are heavier than their displayed size needs.
- perf/total-byte-weight: how much of the page total these images are.
Images findings ship in every audit next to the SEO, performance and agent experience rules. See Core Web Vitals for how an agent works through a report.
References
Check your site
Run squirrel audit https://example.com and open the Images section of the report. Every oversized image is listed with its size and the pages it appears on. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.