qpdf --linearize: Web-Optimize and Repair PDFs
qpdf --linearize in.pdf out.pdf rewrites a PDF for fast web view (linearized), so viewers can render page one before the whole file downloads.
Beyond decryption, qpdf linearizes PDFs for streaming, merges page ranges losslessly, and validates structure. It preserves bytes more faithfully than re-emitting through Ghostscript.
What it does
--linearize reorganizes a PDF for "fast web view" so the first page renders during download. --pages selects and concatenates page ranges from one or more files (a lossless merge/split). --check validates structure without writing output.
Common usage
# web-optimize (linearize)
qpdf --linearize in.pdf out.pdf
# lossless merge of two PDFs
qpdf --empty --pages a.pdf b.pdf -- merged.pdf
# extract pages 1-3 from a file
qpdf in.pdf --pages in.pdf 1-3 -- first3.pdf
# validate a PDF in CI
qpdf --check in.pdfOptions
| Flag | What it does |
|---|---|
| --linearize | Produce a fast-web-view (linearized) PDF |
| --pages ... -- | Select/concatenate page ranges (lossless) |
| --empty | Start from an empty PDF (for pure merges) |
| --check | Validate structure; no output file |
| --object-streams=generate | Compress object streams to shrink output |
| --warning-exit-0 | Return 0 even when warnings occur |
In CI
Use qpdf --pages instead of Ghostscript when you need a lossless merge that keeps annotations and structure. Run qpdf --check as a gate to catch malformed PDFs early. As with decrypt, exit code 3 means warnings (output still written); add --warning-exit-0 so a set -e job does not fail on a recoverable warning.
Common errors in CI
"qpdf: command not found" means install qpdf. "operation succeeded with warnings; resulting file may have some problems" exits 3, which strict pipelines misread as failure; use --warning-exit-0 or check for exit code 2. "unable to find trailer dictionary" or "file is damaged" from --check flags a genuinely corrupt PDF that qpdf may still partly recover. In --pages, forgetting the trailing -- before the output makes qpdf treat the output name as another input.