DEV Community

NullPointerZen
NullPointerZen

Posted on

qpdf --remove-unreferenced-resources=yes removed nothing until --pages . -- was added

The flag name reads like a promise: --remove-unreferenced-resources=yes should strip fonts and images that a page lists in its resource dictionary but never draws. On five PDFs it removed nothing. Each output came out byte for byte the same size as a plain qpdf in out rewrite: 137,382 bytes for a ten-page text-only file, 2,313,754 for a text-plus-photo file, 2,357,545 for a scanned one, 1,496,994 for a NASA fact sheet and 764,524 for a constructed file that stores the same image and font five times.

Scope is narrow: one Apple-silicon Mac, qpdf 12.4.0, every command run once on 2026-11-19. The NASA file is NASA/JPL's "Mars Exploration Rover" NASA Facts (2004) from Wikimedia Commons, public domain. The other samples are self-made with fictional content, and the photo in the text-plus-photo file comes from Wikimedia Commons (CC0). I came to tooling from content work, so each claim below is tagged measured, docs, inference or not investigated.

Five unchanged files proved very little

Five quiet files could simply mean there was nothing unused in them, and that was never checked. So the next sample was a constructed two-page file where both pages share one resource dictionary. That dictionary lists a font F1 that the text uses, a second font F9 that nothing uses and a 200×200 JPEG called ImX that nothing draws. Three versions exist. U0 has a clean content stream at 7,624 bytes. U1 adds an operator that no PDF reader knows, 1 2 foo, and weighs 7,700 bytes. U2 wraps the same kind of thing in a BX … EX block, which the PDF spec sets aside for operators a reader may not recognise, and comes to 7,730 bytes. They are extreme on purpose and say nothing about how often real PDFs carry dead resources.

The flag only worked once pages were rewritten

Here is the run on U1, with file names swapped for placeholders:

$ qpdf --remove-unreferenced-resources=yes page.pdf page-a.pdf && qpdf --remove-unreferenced-resources=yes page.pdf --pages . -- page-b.pdf && wc -c page.pdf page-a.pdf page-b.pdf
    7700 page.pdf
    7783 page-a.pdf
    1148 page-b.pdf
   16631 total
Enter fullscreen mode Exit fullscreen mode

Without --pages the file grew by 83 bytes and all three resources stayed (measured). With --pages . --, which tells qpdf to rebuild the document from its own pages, the output dropped to 1,148 bytes and each page kept only F1, with an empty XObject dictionary (measured). U0 sat at 7,744 bytes with both =auto and =yes and fell to 1,109 with --pages . --. U2 went from 7,806 to 1,171. The short --help text for this option says it removes "any resources that are not referenced in the page's contents" and lists the parameters "auto" (default), "yes" and "no" (docs). It doesn't mention --pages; the full manual was not checked. Why qpdf only applies the removal when pages are rewritten is not investigated, since nobody read the source.

An unknown operator did not stop qpdf

On U1 and U2, qpdf with --pages . -- deleted F9 and ImX even though the content stream contained an operator it could not interpret (measured). Every output rendered the same as its original at 72 dpi, with a maximum pixel difference of 0 (measured). MuPDF printed syntax error: unknown keyword: 'foo' while rendering U1 and then carried on drawing.

A browser tool handled the same three files differently. ImgIng https://imging.ai/ , which I use for compressing PDFs, was run in its lossless structure mode in a desktop browser on the same Mac. On the clean U0 it went from 7,624 to 742 bytes and dropped the unused font and image, but on U1 and U2 it kept F1, F9 and ImX as one group, landing at 7,351 and 7,374 bytes (measured). That small saving most likely came from other structural changes such as object streams (inference, not broken down). ImgIng's renders also matched at 72 dpi, maximum difference 0 (measured).

Why one tool deletes and the other keeps everything is inference. The operands of an unknown operator could be resource names. A private extension might draw an image with /ImX foo, and once ImX is gone a reader that knows the extension has nothing to draw. A tool cannot prove that an operator it doesn't know never refers to a resource, so keeping the whole group is the cautious choice. qpdf seems to decide by the names that appear in the content stream as it parses it. In these samples foo referred to nothing, so deleting F9 and ImX was harmless. A sample where the unknown operator really does use a resource name was not built, and qpdf's source was not read. Nothing here shows qpdf breaking a file.

Checking the flag in a pipeline

If a clean-up script relies on this flag, compare the output size with a plain qpdf in out rewrite. If the two match to the byte, the flag hasn't done anything, and adding --pages . -- is the change that made it act in this test. Before turning that on for files from unknown sources, render a few pages before and after and compare them, because in this run the deletion went ahead whatever operators the content stream contained. My open question is the one this test could not answer: what qpdf does when an unknown operator does name a resource.

Top comments (0)