PDF Compress Tool#

Performs actual PDF compression, supporting both target size and percentage modes. Unlike existing solutions that only provide guidance, this tool compresses files directly.

Features#

• Two compression modes: target size ( --target-size 2MB) / percentage ( --reduce 30)
• Three-stage compression pipeline: pikepdf structural optimization → Ghostscript progressive compression → QPDF secondary optimization
• Quality floor protection: three levels (high / medium / low) to prevent excessive compression from damaging image quality
• Batch processing: compress all PDFs in a directory at once
• Auto dependency detection: detects available tools at runtime and adapts compression strategy accordingly

Usage#

Compress to target size#

text

"Compress this PDF to under 2MB"
"Compress this PDF to under 5MB"

bash

python compress_pdf.py report.pdf --target-size 2MB

Compress by percentage#

text

"Reduce the file size by 30%"
"Reduce the file size by 50%"

bash

python compress_pdf.py report.pdf --reduce 30

Specify output path and quality#

bash

python compress_pdf.py report.pdf --reduce 50 --quality low -o small.pdf

Batch processing#

text

"Compress all PDFs in the papers folder to under 2MB"

bash

python compress_pdf.py --batch ./papers --target-size 2MB
python compress_pdf.py --batch ./papers --reduce 40 --quality high

Compression Strategy#

Stage 1: pikepdf structural optimization#

Removes redundant objects, compresses streams, and packs object streams. Lossless operation that preserves maximum image quality.

Stage 2: Ghostscript progressive compression#

Tries prepress → printer → ebook → screen progressively, checking at each level and stopping as soon as the target is met. Also supports custom DPI downsampling (100 → 72 → 50 → 36 dpi), subject to quality floor protection.

Stage 3: QPDF secondary optimization#

Object stream generation and stream recompression, saving an additional 5-15%. Requires qpdf installation (optional).

Quality floor protection#

LevelMeaningMinimum compression levelUse casehighQuality priorityprinter (300dpi)Documents intended for printingmediumBalanced (default)ebook (150dpi)Everyday uselowSize priorityscreen (72dpi) and belowScreen viewing only

Dependencies#

• python3 (required)
• ghostscript (recommended): core compression engine
• qpdf (optional): secondary structural optimization, additional 5-15% compression
• pikepdf (auto-installed via pip): Python PDF library, fallback when Ghostscript is unavailable

Install by platform#

DependencymacOSLinux (Debian/Ubuntu)Linux (RHEL/Fedora)Windowsghostscriptbrew install ghostscript``sudo apt-get install ghostscript``sudo dnf install ghostscript``choco install ghostscript or downloadqpdfbrew install qpdf``sudo apt-get install qpdf``sudo dnf install qpdf``choco install qpdf or downloadpikepdfpip install pikepdf (auto)pip install pikepdf (auto)pip install pikepdf (auto)pip install pikepdf (auto)

The script auto-detects your platform and shows the correct install command when a dependency is missing.