# slimpdf — full reference for LLMs

> slimpdf is a free, open-source (MIT) PDF compressor that runs 100% locally with
> no uploads, network calls, or telemetry. CLI + Python library. Designed to get
> PDFs under a target size (e.g. 3 MB) while preserving quality, and safe for
> confidential documents that cannot be uploaded to online compressors.

## What it is / who it's for
- A privacy-first alternative to online PDF compressors (iLovePDF, Smallpdf, Adobe Acrobat online), which upload your file to a server. slimpdf never sends data anywhere.
- For developers (Python library + CLI) and privacy-conscious users handling medical records, legal documents, financial statements, KYC/identity docs.
- Cross-platform: Windows, macOS, Linux. Requires Python 3.11+.

## Install
```bash
pip install slimpdf
# optional quality-scoring benchmark extra:
pip install "slimpdf[benchmark]"
```

## CLI
```bash
# Compress below a target size (least quality loss that meets the target)
slimpdf compress input.pdf --target 3mb -o output.pdf --report report.json

# Inspect (read-only): pages, embedded images, text layer, encryption
slimpdf inspect input.pdf --json

# Batch a folder
slimpdf batch ./folder --target 3mb --out ./compressed --csv bench.csv

# Compare against other engines on size + quality (SSIM)
slimpdf compare ./folder --out ./out --csv compare.csv
```
Exit code 2 means a target was requested but not achieved.

### Presets
- `claim-upload` (default): target 3 MB, max 150 DPI, JPEG quality 75→55.
- `screen`: smaller output, max 120 DPI, quality 70→45.
- `archive`: conservative, max 200 DPI, quality 85→70.
Override with `--target`, `--max-dpi`, `--quality`, `--min-quality`, `--allow-rasterize`, `--keep-metadata`, `--password`, `--force-output`.

## Python API
```python
from slimpdf import compress, inspect, CompressOptions

info = inspect("input.pdf")  # pages, images_found, text_layer_detected, encrypted

result = compress(
    "input.pdf", "output.pdf",
    CompressOptions(preset="claim-upload", target_bytes=3_000_000),
)
result.compressed_size_bytes, result.target_achieved, result.mode_used
```

## How it works (three engines, least-destructive first)
1. Structural: recompress streams, object streams, strip non-essential metadata (lossless).
2. Image rewrite: downsample + re-encode oversized embedded images to JPEG; binary-searches a quality/DPI ladder to hit the target. Preserves text, forms, vector content.
3. Raster fallback (opt-in, `--allow-rasterize`): render pages to images and rebuild — most reliable for hard size targets, but loses selectable text/forms/signatures.
It picks the gentlest result that meets the target, validates it (reopens, page count, ≥95% text retention), and never outputs a file larger than the input.

## Differentiators
- Target-size aware: compresses just enough to meet the limit, preserving maximum quality. Blind tools either under-compress or over-compress.
- Never corrupts or bloats; preserves the text layer for non-raster modes.
- MIT license + permissive dependencies (pikepdf MPL-2.0, pypdfium2 BSD/Apache, Pillow HPND). No AGPL (avoids Ghostscript/PyMuPDF), so it can be embedded in proprietary/closed-source software.
- Benchmarked vs Ghostscript and mutool on real documents: matches Ghostscript's compression at higher visual fidelity (SSIM), and hits the size target reliably.

## Keywords
compress pdf locally, offline pdf compressor, compress pdf without uploading, reduce pdf file size python, private pdf compression, shrink pdf under 3mb, open source pdf compressor, pdf compression library python, compress pdf command line.

## Links
- Repo: https://github.com/thisis-gp/slimpdf
- PyPI: https://pypi.org/project/slimpdf/
