tonersave

tonersave rewrites PDFs to use less toner without rasterising pages. Text remains selectable and vector art remains sharp.

It lightens dark inks, removes large dark vector backgrounds, and optionally lightens or removes full-page dark images. Pale content and ordinary photos are normally left alone.

Install

pip install -e '.[gui,dev]'

Python 3.11+ is required. Poppler's pdftoppm enables --stats and GUI previews; conversion itself does not depend on it.

Use

tonersave report.pdf report-eco.pdf
tonersave report.pdf report-eco.pdf --stats --verbose
tonersave slides.pdf slides-eco.pdf --preset aggressive
tonersave report.pdf --in-place --pages 1-4
tonersave report.pdf report-eco.pdf --strict
tonersave-gui report.pdf
# Until the editable package launcher is refreshed, this is equivalent:
python -m tonersave.gui report.pdf

Useful options: --gray controls retained black ink for text and vector marks (default 0.35); --image-gray independently controls retained black ink for raster images (and otherwise follows --gray), --no-backgrounds and --no-images disable their matching reductions, --image-mode is lighten or drop, --image-area sets the minimum image coverage fraction (use 0 to consider every image placement), and --image-darkness controls the normal image brightness gate. --bg-area sets the fraction a fill must occupy before it is treated as a background. --preserve-text keeps native and scanned text at its original ink level while still reducing backgrounds, vector graphics, and raster artwork.

When the text and image ink levels differ, --mask-mode decides which pixels inside a raster image count as text. The default detail keeps dark strokes narrower than --detail-width (in points, default 2.0) at the text level and reduces wider ink masses, so fine print stays crisp while solid artwork lightens; it needs no OCR and is resolution-independent. ocr instead asks Tesseract which words it can read, which is more literal but misses stylized lettering and requires tesseract to be installed. none applies --image-gray to every pixel of an image. Shared images are lightened only once. --verbose reports what was changed, including recognized scans, skipped images, and a reason for each failed page. --strict refuses to write an output when any selected page cannot be converted. In-place conversion preserves the source mode, timestamps, and supported extended attributes (including filesystem ACLs where they are represented as xattrs).

The GUI presents the original and converted page side by side, so each preview shows the actual print-visible effect of the selected settings.

Exit codes are 0 for success, 1 for conversion failure, and 2 for invalid arguments.

Limitations

Tiling-pattern contents are processed, while shading patterns, Separation, and DeviceN constructs are left untouched. Page-level inline images are externalized and then processed through the same safe image pipeline as regular image XObjects. A shared Form XObject is rewritten only once, using the first placement transform observed. Large neutral scans with material sampled ink coverage are lightened even when their paper makes their average brightness appear close to white; bright colour artwork is still left untouched by the normal profile.

See docs/superpowers/specs/2026-08-19-tonersave-design.md for the design.

License

Tonersave is free software licensed under the GNU General Public License, version 3 only. See LICENSE for the complete terms.