Page weight: how heavy is too heavy?

By Matt Kerr·Published 16 September 2026

"How heavy should a page be?" has an answer in Docket, and it is two numbers: 150 KB and 400 KB. Before you measure yourself against either of them, the more useful thing to know is what those numbers are counting — because it is much less than the phrase "page weight" normally means, and on the largest pages it is sometimes not a measurement at all.

What is actually on the scale

The perf.page_weight check weighs the HTML document, decompressed, and nothing else. Not the images. Not the stylesheets, the fonts, the JavaScript bundles or anything those go on to request. The finding says so in its own detail text — "That is the HTML document alone, before images, CSS or JavaScript" — and it is worth reading twice, because most page-weight advice you will find means the total transfer a browser makes to paint the page, and that is a different number, usually a much larger one.

So the two are not interchangeable in either direction. A page can sit comfortably under Docket's lower threshold and still take a long time to load, because the weight is in a hero image and a tag manager. A page can also trip the higher threshold while loading acceptably, because the markup compresses to a fraction of its size on the wire. Docket counts the decompressed bytes — what your server sent, after the transfer encoding is undone — which is the size that matters for parsing and for byte-counted limits, and not the size that left the server.

One more boundary, because it changes what a count means: only pages the crawl actually reached are weighed, and only the ones that answered normally. The check reads ok_pages, which is HTML pages with a 2xx status that were not errors, not bot challenges, not browser gates, and not bodies that turned out to be the site's own repeated navigation. A PDF never appears in this finding. Neither does a page nothing linked to.

The two thresholds, and which one you have

Docket registers this as one check and reports it as two findings, which are two different claims:

• A page over 400 KB — perf.html_very_heavy, at MEDIUM. Named pages, worst first, with the largest one printed by size. This fires on a single page; one is enough.
• A site whose documents are generally large — perf.html_heavy, at LOW. Pages between 150 KB and 400 KB, and it fires only if more than half of the crawled pages are in that band.

Two properties of that second one are easy to misread. It is an alternative, not an addition: if any page tripped the MEDIUM branch, the LOW finding does not appear at all, so the absence of "HTML documents are larger than they need to be" is not evidence that your other pages are small. And it is a statement about the shape of the site rather than about any page — a handful of fat templates on an otherwise lean site will not reach the majority and will not be reported here.

The KB in both is decimal — a thousand bytes, not the 1024 a lot of tools mean by the same two letters. Docket publishes every measured size through one divisor, which exists because two findings once described the same page in two units inside the same report, each correct in its own file and disagreeing with its neighbour. If you convert Docket's KB yourself, divide by a thousand and you will land where it did.

When the number is a floor and not a size

This is the part worth knowing before you act on any oversized-page finding, in Docket or anywhere else.

Docket's fetcher stops reading a response at 8 mebibytes, which is 8.4 MB in the decimal unit its findings print. That is deliberate — the comment at the constant calls it "~20x the 95th percentile HTML page; anything past it is a download, not a document" — and it keeps one pathological URL from eating a crawl. The consequence is the interesting bit. Whatever the page really weighs, the bytes Docket holds stop there:

if len(raw) > self.max_bytes:
    raw = raw[: self.max_bytes]
    truncated = True

For a while the checks never saw that flag. The fetcher recorded it, the extractor dropped it, and the page-weight finding printed the ceiling as though it were the measurement. Found on 8 September 2026 on a large resources hub: Docket reported 8388 KB, and fetching the same URL returned 10,152,527 bytes — about 10.2 MB. The report understated the page by 1.76 MB while sounding precise to the kilobyte.

The tell was that the figure was a round power of two. 8388 KB is exactly 8 mebibytes, and no real page is that size by coincidence. If a tool hands you a page size that is suspiciously round in binary — a ceiling number rather than a measured one — check whether you are reading the page or reading the tool's limit. That applies to whatever crawler you use, not only to this one.

What the shipped build does now is carry the flag across and change the sentence. One line in the extractor:

page.body_truncated = bool(getattr(resp, "truncated", False))

and the finding prefixes its size with "at least" when that flag is set. So the report reads "Largest: at least NNN KB on that URL" for a capped read, and prints the exact figure with no hedge for every page read to the end. That partition is the point, and it has its own test: saying "at least" on every heavy page would turn hundreds of exact, correct figures into guesses.

Two caveats on the flag, both true of the code as it stands. It is set on the perf.html_very_heavy finding, which is the one that prints a named page's size — the LOW finding prints a count and no per-page figure, so there is nothing there to hedge. And truncation has a second cause besides the ceiling: the fetcher reads against a wall-clock deadline, and a server that answers quickly and then dribbles the body gets cut off at the deadline with whatever arrived kept and marked truncated. A partial read is still worth something — the alternative is discarding work already paid for — but it means "at least" can mean "your server was slow" as well as "your page was enormous".

So how heavy is too heavy?

Treat 400 KB as a line worth investigating rather than a rule, because the web does not respect it. We measured the homepages of the sites in our own sample list on 2026-08-07 for a different article: of the 82 that answered, 68 are over 150 KB and 50 are over 400 KB, and the median is 479 KB of HTML. The median well-known homepage is past Docket's upper threshold. Those thresholds are strict on purpose, and a finding at MEDIUM is an invitation to look rather than a verdict that your site is broken.

The honest reason to care is not a ranking penalty, and this page will not claim one. The finding's own detail says a heavy document "delays the first paint by seconds" on a phone connection — an inference from the size, not something Docket timed, and worth weighing accordingly. The repository is blunter about this elsewhere: a note in the crawler records that of two sites measured with the shipped renderer, the one serving 136 KB rendered slower than the one serving 643 KB, and concludes "do not tune this cap against document size". Whatever dominates the time is script execution and the network waterfall, and it has not been isolated.

What document size does control, exactly and without inference, is a byte budget: Googlebot stops reading at 2MB, headers included, and hands the fragment it got to indexing as though it were the whole file. That is a different check with a different threshold, and it is the one where a large document silently costs you something. If you only read one of the two pages, and your documents are genuinely large, read that one.

Measuring it yourself

Docket's number is reproducible in one line. This is the count it takes — the decompressed HTML document, nothing referenced:

curl -sS --compressed https://example.com/ | wc -c

Drop --compressed and you get the bytes as they would arrive if your visitor's browser did not negotiate an encoding. Ask for gzip explicitly and count again, and the difference between the two is what compression is saving you on this page:

curl -sS -H 'Accept-Encoding: gzip' https://example.com/ | wc -c

If those two numbers are the same, the document is not being compressed at all, which is a separate finding and a much cheaper fix than trimming markup — how to fix compression and caching headers covers it. Doing that first is the right order: compression changes what the visitor waits for without changing a line of your templates.

What actually makes a document heavy

The check's own remedy names the usual causes, and after a few hundred crawls they are reliably the same three:

1. Inlined CSS and JavaScript. Every page carries its own copy, so nothing is cached across pages and the same bytes are paid for again on every navigation. Moving them into linked files removes them from the document entirely.
2. Base64 images inlined into the markup. An encoded image is larger than the file it came from, and it lands in the one budget that counts here.
3. A whole listing rendered into one page. An entire catalogue, or navigation that prints thousands of links before the content starts. The fix is pagination, and it usually helps more than the byte count suggests.

The check's fix text is one sentence for the first and third of those: move inline blocks to cached external files, and paginate long listings. Note what that does to the second finding as well — external files are cached across pages, so the site-wide LOW finding tends to close on the same edit.

One caveat if your pages are built by JavaScript: the document Docket weighed is the one your server sent, before any of it ran. What JavaScript rendering costs you covers why the served document and the finished page can be very different sizes, and which one each tool is looking at.

Reading your own finding

The list attached to any finding is capped at 25 URLs while the count beside it keeps the true total, so "showing 25 of a larger number" means exactly that. On the MEDIUM finding that list is sorted heaviest first, so the pages you cannot see are the smaller ones; the LOW finding lists its band in crawl order. Start at the top, check whether the largest figure carries an "at least", and if it does, fetch that URL yourself before deciding how bad it is. Everything else on the list is a measurement you can trust to the kilobyte.

Download Docket

Common questions

What counts as page weight in Docket?

The HTML document on its own, decompressed, and nothing it references. Images, stylesheets, fonts and JavaScript bundles are not in the number, so a page that passes this check can still be slow to load. Most page-weight advice means the total a browser downloads, which is a different and usually much larger figure.

How heavy is too heavy for a web page?

Docket draws two lines on the HTML document: one at a hundred and fifty kilobytes, which it only reports when more than half the crawled pages sit in that band, and one at four hundred kilobytes, which it reports for a single page. Both are strict compared with the real web — the median homepage in our own sample of well-known sites is past the higher of the two.

Why does my report say 'at least' before a page size?

Because the crawler stopped reading before the page ended, so the figure is the point it stopped at rather than the size of the document. That happens when a response passes the fetcher's eight-mebibyte read ceiling, and also when a slow server is still dribbling the body when the deadline expires. Fetch the URL yourself to get the real size.

Does page weight affect Google rankings?

This page does not claim a ranking penalty, because Docket has not measured one and the finding's own note about delaying first paint is an inference from the size rather than something timed. What document size provably controls is Googlebot's byte budget: it reads a fixed amount of any URL and indexes that fragment as if it were the whole file.

Is a large HTML file the same as a slow page?

No, and the repository records a case against assuming it. Of two sites measured with the shipped renderer, the one serving roughly a sixth of the markup rendered slower than the heavier one, and the note concludes that document size should not be used to predict render cost. Script execution and the network waterfall dominate, and neither is visible in a byte count.