pdf-slim/README.md

pdf-slim

Losslessly shrink a PDF. The output renders pixel-for-pixel identically to the input; any candidate that doesn't is discarded.

How it works

pdf-slim builds several smaller candidates and keeps the smallest one that passes verification. The input file is never modified.

1. Structural — qpdf object-stream generation and maximum-level flate recompression. Always render-safe; a modest win.
2. mutool-subset — mutool clean garbage-collects, deduplicates, deflates, and natively subsets fonts.
3. font-resubset — for any TrueType FontFile2 stream still over a size threshold (the "Word embedded the whole font" case), the font is re-subset with pyftsubset against the document's actual character set. Glyph IDs are retained (--retain-gids) so CID / Identity-H instances sharing the file stay valid. The stream is spliced back, lengths are fixed with fix-qdf, and the result is recompressed.

Every candidate is verified by rendering each page of both the original and the candidate at the same DPI and requiring byte-identical pixels. The smallest verified candidate wins. If nothing wins by more than 1%, the input is copied through unchanged, so repeated runs are stable.

Usage

pdf-slim input.pdf [output.pdf] [--dpi 200] [--min-font-bytes 150000]

• input.pdf — the PDF to shrink.
• output.pdf — optional; defaults to <input>-slim.pdf. Refuses to overwrite the input.
• --dpi — verification render resolution (default 200).
• --min-font-bytes — re-subset embedded TrueType fonts larger than this (default 150000).

Example

[ phanes@forge.silogroup.lan ] << ~/Downloads >>

[- du -sh 2026-06-08*
28K    2026-06-08.docx
1.8M    2026-06-08.pdf

[ phanes@forge.silogroup.lan ] << ~/Downloads >>

[- pdf-slim 2026-06-08.pdf 2026-06-08-small.pdf
input:  2026-06-08.pdf  (1,852,511 bytes)
method: font-resubset (pixel-identical at 200 dpi)
output: 2026-06-08-small.pdf  (192,810 bytes, -89.6%)

[ phanes@forge.silogroup.lan ] << ~/Downloads >>

[- du -sh 2026-06-08*
28K    2026-06-08.docx
1.8M    2026-06-08.pdf
192K    2026-06-08-small.pdf

Requirements

The following tools must be on PATH:

• mutool (MuPDF)
• qpdf (provides qpdf and fix-qdf)
• pyftsubset (fontTools)
• python3

Ownership

Owned by SILO GROUP — www.silogroup.org.

License

Copyright (C) 2026 SILO GROUP (www.silogroup.org).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See LICENSE for the full text.