QuantPDF CLI

🎯 Target-size PDF compression from the command line

Compress PDFs to an exact target size, locally and privately.

Features • Installation • Quick Start • Documentation • GUI Version

🇨🇳 中文

---

🌟 Why QuantPDF CLI?

Most PDF compression tools offer vague "Low/Medium/High" quality settings. QuantPDF CLI is different:

• 🎯 Target-Oriented: Specify exact output size (e.g., "compress to 25MB")
• 🔒 Privacy-First: 100% local processing, no uploads, no cloud
• 📊 Smart Optimization: Prioritizes text readability over aggressive downsizing
• ⚡ Fast & Efficient: Optimized for large scanned PDFs
• 🆓 Free & Open Source: MIT License, use anywhere

✨ Features

Core Capabilities

• ✅ Exact target size - Set 25MB, get 25MB (±5% accuracy)
• ✅ Local processing - Files never leave your machine
• ✅ Smart compression - Maintains readability while reducing size
• ✅ Multiple passes - Iterative optimization for better results
• ✅ Flexible DPI - Choose from 100-300 DPI
• ✅ Color modes - Color, Grayscale, or Black & White
• ✅ Progress tracking - Real-time JSON progress output
• ✅ Batch processing - Process multiple files via scripting

Perfect For

• 📄 Government forms with strict size limits (10-25MB)
• 🎓 Academic submissions and applications
• 💼 Job applications with resume size caps
• 📁 Archiving large scanned documents
• 📧 Email attachments with size restrictions

📦 Installation

Via pip (Recommended)

pip install quantpdf-cli

From source

git clone https://github.com/paradoxie/quantpdf-cli.git
cd quantpdf-cli
pip install -r requirements.txt

System Requirements

• Python: 3.8 or higher
• Poppler: Required for PDF processing

Install Poppler:

macOS:

brew install poppler

Ubuntu/Debian:

sudo apt-get install poppler-utils

Windows: Download from Poppler for Windows

🚀 Quick Start

Basic Usage

# Compress to 25MB
quantpdf input.pdf output.pdf --size 25

# Compress to 10MB with 150 DPI
quantpdf input.pdf output.pdf --size 10 --dpi 150

# Compress to grayscale
quantpdf input.pdf output.pdf --size 20 --mode grayscale

Advanced Usage

# Maximum quality with 3 optimization passes
quantpdf input.pdf output.pdf --size 25 --dpi 300 --max-passes 3

# Black & white for text documents
quantpdf input.pdf output.pdf --size 5 --mode bw --dpi 200

# With progress logging
quantpdf input.pdf output.pdf --size 25 --log compression.log

Command-Line Options

usage: quantpdf [-h] --input INPUT --output OUTPUT --size SIZE
                [--dpi DPI] [--mode {color,grayscale,bw}]
                [--max-passes PASSES] [--log LOG]

Required arguments:
  --input INPUT         Input PDF file path
  --output OUTPUT       Output PDF file path
  --size SIZE           Target size in MB (e.g., 25 for 25MB)

Optional arguments:
  --dpi DPI             DPI for images (100-300, default: 200)
  --mode MODE           Color mode: color, grayscale, bw (default: color)
  --max-passes PASSES   Max optimization passes (1-3, default: 2)
  --log LOG             Log file path for debugging
  -h, --help            Show this help message

📖 Documentation

User Guides

• Installation Guide - Detailed installation instructions
• Usage Guide - Complete usage examples
• API Documentation - Python API reference
• Troubleshooting - Common issues and solutions

Technical Documentation

• Compression Strategy - How compression works
• Protocol Documentation - CLI protocol specification
• Packaging Guide - Building and distribution

💡 Examples

Example 1: Job Application

# Compress resume to meet 10MB limit
quantpdf resume_scanned.pdf resume_compressed.pdf --size 10 --dpi 200

Example 2: Batch Processing

# Process all PDFs in a directory
for file in *.pdf; do
  quantpdf "$file" "compressed_$file" --size 25
done

Example 3: Python Integration

import subprocess
import json

def compress_pdf(input_path, output_path, target_mb):
    """Compress PDF with progress tracking"""
    process = subprocess.Popen(
        ['quantpdf', input_path, output_path, '--size', str(target_mb)],
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True
    )
    
    for line in process.stdout:
        event = json.loads(line)
        if event['type'] == 'progress':
            print(f"Progress: {event['percent']}%")
        elif event['type'] == 'complete':
            print(f"Done! Final size: {event['finalSizeMb']}MB")
    
    return process.wait()

# Usage
compress_pdf('input.pdf', 'output.pdf', 25)

See more examples in the examples/ directory.

🖥️ GUI Version

Want a simpler, visual experience?

QuantPDF is also available as a native macOS app with:

• 🖱️ Drag-and-drop interface
• 👁️ Real-time preview
• 📦 Batch processing queue
• 💾 Custom presets
• 📊 Compression history
• 🔄 Automatic updates

Download QuantPDF for macOS →

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Start for Contributors

# Fork and clone the repo
git clone https://github.com/paradoxie/quantpdf-cli.git
cd quantpdf-cli

# Install development dependencies
pip install -r requirements.txt
pip install pytest black flake8

# Run tests
pytest tests/

# Format code
black quantpdf_cli.py

# Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Pillow for image processing
• Uses pdf2image for PDF conversion
• Powered by Poppler for PDF rendering

📞 Support

• 🐛 Bug reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: support@quantpdf.com
• 🌐 Website: quantpdf.com

⭐ Star History

If you find this project useful, please consider giving it a star! ⭐

---

Made with ❤️ by the QuantPDF team

Website • GUI Version • Documentation