Run qpdf --show-xref on a plain text-only PDF and every line looks like 2/0: uncompressed; offset = 131. Rewrite the file with --object-streams=generate, run it again, and the second line reads 2/0: compressed; stream = 1, index = 0. In this test the file went from 137,782 to 132,065 bytes, 4.15% smaller, same 10 pages, same text. I knew the words "xref table" and "object stream" but couldn't have explained that one-line change, so here is the beginner's model that made it readable, plus the part I didn't expect: 4% is close to the ceiling for this file. The test file is a 10-page text-only report with fictional content and an embedded Chinese font subset, run once on one Apple-silicon Mac with qpdf 12.4.0, so every number means "this file, this run".
The xref table is a list of byte offsets
A PDF is a pile of numbered objects: pages, fonts, content streams, and a catalog pointing at the page tree. A reader doesn't scan the whole file to find object 2. At the end of a classic PDF sits the cross-reference table, the xref, with one entry per object number giving the byte where that object starts. The trailer after it points at the root, and a startxref line says where the table itself is. So opening a PDF is roughly: jump to the end, find the xref, read the offsets, seek straight to the object you need.
$ qpdf --show-xref notes.pdf | head -3 1/0: uncompressed; offset = 61 2/0: uncompressed; offset = 131 3/0: uncompressed; offset = 238 2/0 is object 2, generation 0, starting at byte 131. Object 1 starts at byte 61 because the first 61 bytes are the file header. This file has 37 top-level objects, and the table plus trailer take 977 bytes, 0.71% of the file.
After object streams the offsets point into a stream
PDF 1.5 added two features that travel together. An object stream is one stream object holding many small non-stream objects (dictionaries, arrays, numbers) back to back, Flate-compressed as a whole. An object inside a compressed stream has no byte offset of its own, so a plain-text table can't describe it. That's why the cross-reference stream exists: the xref becomes a compressed stream whose entries say either "starts at byte N" or "item i inside object stream S".
$ qpdf --object-streams=generate notes.pdf notes-os.pdf && wc -c notes.pdf notes-os.pdf 137782 notes.pdf 132065 notes-os.pdf 269847 total $ qpdf --show-xref notes-os.pdf | head -3 1/0: uncompressed; offset = 15 2/0: compressed; stream = 1, index = 0 3/0: compressed; stream = 1, index = 1 With that model the new lines make sense. Object 1 is a normal object at byte 15, and stream = 1 says objects 2 and 3 live inside it at positions 0 and 1, so object 1 is the object stream. This run didn't check whether the new object 2 is the same object as the old one, since qpdf writes a whole new file, so I read it only as "small objects moved into object 1". Stream objects such as fonts and page content can't go inside an object stream at all, so they keep showing "uncompressed" with an offset even though their data is Flate-compressed. Here "uncompressed" means "not inside an object stream", and that's the word that is easy to misread.
The saving is bigger than the bookkeeping
The first half of this is subtraction. A plain qpdf rewrite with no options already gave 137,382 bytes, so object streams account for 5,317 of the 5,717. Page and structure objects took 2,685 bytes and the xref plus trailer 977. Even if both vanished, that's 3,662, short of 5,317. The rest turns up when the original's bytes are split into stream and non-stream objects: 3,512 of the font bytes are non-stream objects such as font dictionaries and /W width arrays, which an object stream can pack and compress. After the rewrite 3,536 bytes had left the font column and moved into the 1,206-byte object stream along with the page objects. A constructed file that stores one font five times shows the same effect more loudly, its font bytes going from 266,381 to 134,332 with object streams on.
Fonts are 88% of this file so the ceiling is low
Fonts take 121,442 bytes (88.14%) and content streams 12,617 (9.16%), and object streams leave the font data itself alone. Stacking --recompress-flate --compression-level=9 on top reached 130,933 bytes, −4.97%. The reverse check shows why little is left: writing the file with every stream decompressed made it 309,649 bytes, 2.25 times the original. Image-heavy files gain even less. Object streams alone made a scanned PDF 0.02% smaller and a text-plus-photo PDF 0.74% smaller, since images are 99.84% and 95.93% of their bytes. The photo in that second sample comes from Wikimedia Commons (CC0).
For compressing PDFs I use ImgIng https://imging.ai/ , which processes the file locally in the desktop browser. Its lossless structure mode took the same text file to 131,156 bytes, −4.8%, the same range as qpdf with everything on, and left the scanned file almost unchanged at −0.03%, which matches the breakdown.
To check your own file, qpdf --show-xref yourfile.pdf | head is enough. If every line says "uncompressed; offset", the file uses a classic xref table and --object-streams=generate may save a few percent. If lines already say "compressed; stream", it was probably written with object streams and there's little structural slack left. Compare wc -c before and after, and when a text-only PDF barely moves, the bytes are most likely in the fonts.
