How to linearize a pdf for fast web page loading
- Step 1Open the linearizer and drop your PDF — Load the document into the PDF Linearize (Fast Web View) tool. It accepts a single PDF (
acceptsMultipleis off) — drop one file at a time. - Step 2Leave the password field blank for a normal PDF — The only reason to type anything here is an encrypted input. The placeholder reads 'Leave blank for unencrypted PDFs' — that is the common case for web-delivered documents.
- Step 3Decide whether to tick Force — Leave Force off for normal use: if the file already has a
/Linearizeddictionary the tool returns it unchanged. Tick 'Re-linearize even if the input is already linearized' only when you've edited the file in another tool and want qpdf to rebuild the hint stream from scratch. - Step 4Run and let qpdf-wasm rebuild the byte order — qpdf rewrites the cross-reference table and writes the first-page hint dictionary at the front of the file. This is the heavy step; it happens locally in WebAssembly, so larger files take a moment.
- Step 5Download the linearized PDF — Save the output. It is a standard PDF — every reader opens it identically; the only difference is the internal ordering that enables progressive rendering.
- Step 6Replace the file on your web server — Upload the linearized version over the old one. For the progressive-load benefit to reach visitors your server must answer HTTP byte-range requests (
Accept-Ranges: bytes) — Apache, Nginx, and most CDNs do this by default for static files.
The two options this tool actually exposes
The linearizer has exactly two UI controls. There is no target-size, no quality slider, and no compression option — by design, because linearization is a structural reorder, not a size operation.
| Control | What it does | Default | When to change it |
|---|---|---|---|
| Password (text field) | Passed to qpdf as --password=… so it can decrypt an encrypted input, linearize, and re-encrypt in one pass | Empty | Only when the PDF is password-protected. Leave blank otherwise |
| Force (checkbox) | 'Re-linearize even if the input is already linearized' — skips the already-linearized fast-path and makes qpdf rebuild the hint stream | Off | When you edited the file elsewhere after a previous linearize and want a clean rebuild |
What linearization changes — and what it does not
Linearization touches byte order only. Reach for a sibling tool when you actually need to change content or size.
| Goal | Does linearize do it? | Use instead |
|---|---|---|
| Render page 1 before the file finishes downloading | Yes — this is the entire job | — |
| Make the file smaller | No — structure-only reorder, size is roughly unchanged | Lossless compress first, then linearize |
| Shrink a scan to a hard target | No | Aggressive compress |
| Strip metadata bloat | No | Metadata scrubber |
| Change the PDF version for an old reader | No | Version converter |
Per-tier file and page limits (PDF family)
Linearization is in-browser, so the practical ceiling is your tab's memory; these tier caps gate the input you can load.
| Tier | Max file size | Max pages | Batch files |
|---|---|---|---|
| Free | 2 MB | 50 | 1 |
| Pro | 50 MB | 500 | 5 |
| Pro Media | 500 MB | 2,000 | 50 |
| Developer | 2 GB | 10,000 | unlimited |
| Enterprise | unlimited | unlimited | unlimited |
Cookbook
Concrete runs against the two controls this tool exposes. The 'before/after' is the file's internal state, not a size change.
The normal case — an unencrypted report
A 4 MB marketing PDF exported from InDesign, served from your site. No password, first time through.
Options:
password: (blank)
force: off
Before: xref table at end of file, no /Linearized dict
After: /Linearized hint dictionary written at front
Acrobat → File → Properties → 'Fast Web View: Yes'
Size: ~unchanged (structural reorder, not compression)Already-linearized input is passed through untouched
You re-run last week's deploy. The file you upload was already linearized. With Force off, the tool detects the existing hint stream and returns the bytes unchanged — no redundant rebuild.
Options: password: (blank) force: off inspectLinearization() finds <</Linearized /L … /N …>> in head → alreadyLinearized: true → output bytes == input bytes (no work done)
Force a clean rebuild after editing elsewhere
You linearized once, then ran the file through another editor that left the old hint dict stale. Tick Force to make qpdf rebuild it from scratch.
Options: password: (blank) force: ON → fast-path skipped even though /Linearized was present → qpdf --linearize rebuilds the hint stream cleanly
Compress first, then linearize
The correct order for a large web PDF. Linearization will not shrink the file, so do the size work first.
Step 1: pdf-compress-lossless → 4.2 MB → 2.9 MB (text kept) Step 2: pdf-linearize → 2.9 MB, Fast Web View: Yes Linearizing first then compressing would discard the byte ordering — always linearize last.
Encrypted input with a password
A client-portal PDF protected with an open password. Supply it so qpdf can do the round-trip in one pass.
Options: password: hunter2 force: off qpdf --password=hunter2 --linearize in.pdf out.pdf → decrypts, linearizes, re-encrypts in a single pass → output stays encrypted with the same password
Edge cases and what actually happens
PDF is already linearized and Force is off
Passed throughThe tool sniffs the first 4 KB of the file for a <</Linearized … >> dictionary. If it finds one and you have not ticked Force, it returns your file unchanged and reports it as already linearized. This is intentional — re-linearizing an already-linearized file is wasted work. Tick Force only if you specifically want a fresh rebuild.
Encrypted PDF, no password supplied
Errorqpdf refuses to touch an encrypted file without credentials and exits with code 2. The tool surfaces this as 'qpdf could not process this PDF — it may be corrupted or use an unsupported encryption.' Type the open password into the password field and re-run; qpdf will decrypt, linearize, and re-encrypt in a single pass.
You expected the file to get smaller
By designLinearization reorders the PDF's internal structure; it does not recompress images or strip data, so the size is roughly unchanged. To reduce size, run lossless compression (keeps text) or aggressive compression (for scans) first, then linearize the smaller file last.
Server does not support byte-range requests
No web benefitThe linearized file is valid, but the progressive-load win only appears when the server answers Range: headers with Accept-Ranges: bytes. Apache and Nginx do this for static files by default; some app frameworks streaming a PDF through a handler do not. Verify with curl -I and look for Accept-Ranges: bytes.
qpdf finished with warnings
Supportedqpdf exit code 3 means warnings only — it still produced a valid linearized output. The tool treats codes 0 and 3 as success and returns the file. Warnings usually come from minor structural quirks qpdf repaired while rebuilding the xref table; the output is safe to use.
Corrupted or truncated PDF
ErrorIf the input is damaged badly enough that qpdf cannot parse it, it exits 2 and the tool reports it could not process the file. Run the PDF Repair tool first to rebuild the structure, then linearize the repaired output.
Very large multi-hundred-page PDF on the Free tier
LimitFree caps PDF input at 2 MB and 50 pages. A large web report will exceed that. Either compress it under 2 MB first or upgrade — Pro raises the cap to 50 MB / 500 pages. Linearization itself runs in WebAssembly in your tab, so the real-world ceiling above that is browser memory.
File is under ~1 MB
Minimal benefitBelow roughly 1 MB a browser downloads the whole file fast enough that progressive rendering is barely perceptible. Linearization is harmless on small files but the user-visible win is on the larger documents (multi-megabyte brochures, reports, catalogues) that actually take time to fetch.
PDF/A archival file
PreservedLinearization is a structural byte-ordering property, not a content change, so a PDF/A file can be linearized and remain conformant. If you specifically need to produce PDF/A, use the PDF/A converter; linearize afterward if it is also web-served.
Frequently asked questions
What does linearizing actually do to my PDF?
It reorders the file's internal bytes so the cross-reference information and a first-page hint dictionary sit at the front. That lets a viewer render page 1 from the first chunk of bytes instead of downloading the whole file first. Your content — text, images, links, bookmarks — is untouched; only the byte ordering changes.
Does linearization reduce file size?
No. It is a structural reorder, not compression, so the size is roughly unchanged. Compress first with lossless compression for text PDFs or aggressive compression for scans, then linearize the result last so the byte ordering survives.
How do I verify a PDF is linearized?
Open it in Acrobat or Acrobat Reader, go to File → Properties → Description, and look for 'Fast Web View: Yes'. The tool writes the same /Linearized hint dictionary Acrobat checks for, so that field flips to Yes.
Is my document uploaded to a server?
No. The linearizer runs qpdf compiled to WebAssembly directly in your browser tab. The PDF never leaves your device — which matters for internal reports and client documents that happen to be web-served.
What engine does this use?
qpdf compiled to WebAssembly. qpdf is the reference implementation for PDF linearization — it produces the same /Linearized hint stream Acrobat does, self-hosted as a ~1.3 MiB WASM module that loads once per session.
What happens if my PDF is already linearized?
The tool sniffs the file header for an existing /Linearized dictionary. If it finds one and you have not ticked Force, it returns your file unchanged so you don't pay for redundant work. Tick the Force checkbox to re-linearize anyway.
What is the Force checkbox for?
It is labelled 'Re-linearize even if the input is already linearized'. Leaving it off lets the tool skip files that already have the hint stream. Turn it on when you've edited a previously-linearized file in another tool and want qpdf to rebuild the hint stream from scratch.
Does it work on encrypted PDFs?
Yes — type the open password into the password field. qpdf decrypts, linearizes, and re-encrypts in a single pass, and the output stays encrypted with the same password. Without the password an encrypted input fails with a 'could not process this PDF' error.
Will text stay selectable after linearizing?
Yes. Unlike lossy compression, linearization does not rasterize anything. Selectable text, hyperlinks, the bookmark outline, and form fields all survive — only the byte ordering changes.
Do I need to configure my web server?
For the progressive-load benefit to reach visitors, the server must answer HTTP byte-range requests with Accept-Ranges: bytes. Apache, Nginx, and most CDNs do this for static files by default. Check with curl -I https://yoursite/file.pdf and look for the Accept-Ranges header.
Is a linearized PDF compatible with all readers?
Yes. A linearized PDF is a fully standard PDF — every reader, browser viewer, and upload portal opens it identically. The only difference is the internal ordering that enables progressive rendering in viewers that support it.
How big a PDF can I linearize?
The tier caps gate the input: Free allows 2 MB / 50 pages, Pro 50 MB / 500 pages, Pro Media 500 MB / 2,000 pages, Developer 2 GB / 10,000 pages, Enterprise unlimited. Because qpdf runs locally in WebAssembly, the real-world ceiling above those caps is your browser tab's memory.
Privacy first
All PDF processing runs locally in your browser using PDF-lib and pdf.js. No file is ever uploaded — only metadata counters are saved for signed-in dashboard stats.