Hyper Compress

💖 Thank You to Our Sponsors

The best open source PDF compression engine.

Hyper Compress is a high fidelity, content preserving PDF compression engine built to make PDFs smaller without unnecessarily changing the document.

Hyper Compress is built by the BentoPDF team. The same engine is available as a CLI, a Node.js SDK and a Rust crate (both on one Rust core), a C library, a self-hosted HTTP service, and a WebAssembly build that runs entirely in the browser.

Try it at hyper.bentopdf.com. Full documentation lives at hyper.bentopdf.com/docs.

📜 Licensing

Hyper Compress is dual-licensed to fit your needs:

Solo $99 · Indie $199 · Business $499 per year · One closed-source product per license · Unlimited developers from Indie up · No AGPL obligations

Using BentoPDF? Its commercial license already includes Hyper Compress as a bundled component for eligible products (companies under US$1 million in revenue and funding, through BentoPDF's own tools on the end user's device). Using the engine on its own, on a server, through an API or in other software needs a Hyper Compress license.

For OEM terms, contact [email protected]. See the full license terms and the pricing page.

📖 For more details, see the Licensing Page.

Table of Contents

• Why Hyper Compress

• Benchmarks

• Install

• Usage

  • CLI
  • Node.js SDK
  • Self-hosted service
  • Browser (WebAssembly)
  • C API

• Compression Levels

• What the Engine Does

• Building from Source

• Testing

• Project Layout

• Licensing

• Contributing

Why Hyper Compress

PDF compression has three major problems: files ending up being larger after compression, sacrificing document content for size, and producing PDFs that are broken and non conforming.

Hyper Compress is built around solving these three problems.

• Monotonic compression. Hyper never returns a larger file. If compression does not save space, the original PDF is returned unchanged.

• Content preserving compression. Hyper includes a true lossless mode for compression without image re encoding or quality loss. For more aggressive compression, it preserves searchable text and document structure while making only the changes required by the selected compression level all while producing a conforming PDF.

• Signed documents handled safely. A digitally signed PDF is returned byte for byte by default, so its signature stays valid. Set removeSignatures to compress it anyway: Hyper removes the digital signature, keeps the visible signature on the page, compresses the document and reports signaturesRemoved, so the file can be signed again.

• Built for reliability. Hyper validates its output and verifies transformations that can affect visual fidelity. When a change cannot reproduce a page faithfully, it is rolled back. Across the benchmark, Hyper had a 0.39% corruption rate, the lowest of any engine measured.

• One engine, everywhere. The same compression engine powers the CLI, the Node.js SDK, the Rust crate, the C API, the self-hosted service and the WebAssembly build, on macOS, Linux (x64 and ARM64) and Windows.

Benchmarks

Against commercial SDKs: PDF Tools, Apryse and Nutrient

Hyper Compress was benchmarked against the PDF Tools, Apryse and Nutrient SDKs on 1,000 real PDFs (3.13 GB) from five public sources, at four levels, for a total of 13,000 engine runs. We make Hyper, so everything needed to check or repeat these numbers is in bench/sdk-comparison/: the exact list of PDFs with download links and checksums, every per-file result, and the code.

Each engine's settings were taken from its own documentation to match each level as closely as its options allow. If you know a setting that would serve an engine better at the same level, open an issue and we will rerun it.

Size saved overall, @ average page quality (SSIMULACRA2, where 100 is identical):

Robustness across the same benchmark:

[!NOTE] PDF Tools, Apryse and Nutrient have no lossless mode: none of their documentation describes a lossless optimization setting, so their lossless results are N/A.

python3 fetch_corpus.py                        # downloads the 1,000 PDFs and checks every SHA-256
npm install                                    # hyper-compress 1.1.4
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt --extra-index-url https://pypi.apryse.com
dotnet build engines/nutrient -c Release -o engines/nutrient/bin
export APRYSE_KEY=... PDFTOOLS_KEY=... NUTRIENT_KEY=...   # your licence keys
./run.sh                                       # writes results.csv (takes several hours)
python3 report.py results.csv                  # prints the tables above

Against open-source tools: Ghostscript, MuPDF and qpdf

Hyper Compress was benchmarked against Ghostscript, MuPDF, and qpdf using 2,104 real world PDFs from four public corpora, for a total of 27,352 engine runs.

Visual fidelity was measured with Poppler, which was deliberately chosen as an independent renderer rather than one shared by the engines being tested.

The full methodology, per-file results, and complete document list are available in comparison.md.

Median size reduction at the median worst page SSIM:

Robustness across the same benchmark:

[!NOTE] The corpus selection was pre registered using a fixed seed before any files were fetched. Every document's SHA-256 hash and origin URL are recorded, so the benchmark can be independently reproduced.

You can also run the harness against your own documents:

make bench CORPUS=path/to/corpus

Install

Prebuilt binaries for macOS, Linux, and Windows are attached to each release.

Download the archive for your platform, verify it against SHA256SUMS, and unpack it into cli/prebuilt/.

For the self-hosted service:

docker run -d -p 8080:8080 ghcr.io/alam00000/bentopdf-hyper-compress:latest

To build the engine yourself, see BUILDING.md.

Usage

CLI

hyper input.pdf                                     # writes input-compressed.pdf

hyper input.pdf output.pdf                          # medium preset (default)

hyper input.pdf output.pdf --preset high            # smallest output

hyper scan.pdf out.pdf --target-size 2MB            # specify a target size

hyper locked.pdf out.pdf --password hunter2         # encrypted input

hyper in.pdf out.pdf --set grayscale=true           # override an option

hyper --help                                        # every flag, with examples

--target-size searches for the highest image quality that fits under your target, pushing down to quality 5 and 36 dpi if it has to. If the target is reachable you get the best looking file that fits; if it is not, you get the smallest file the engine could produce along with a warning saying how small that was.

Node.js SDK

import { compress } from 'hyper-compress';

const r = await compress({
  sourcePath: 'input.pdf',
  savePath: 'output.pdf',
  preset: 'medium',
});

console.log(r.originalSize, '->', r.compressedSize);

The result includes the original and compressed sizes, whether the document was signed, its declared PDF/A level, and whether a requested target size was reached.

Errors are typed:

decrypt_failed, engine_error, timeout, cancelled.

Parsing runs in a worker subprocess with a timeout. If hostile or malformed input causes the worker to fail, it is isolated from your main process.

Self-hosted service

The Docker image includes a web interface at http://localhost:8080 and an HTTP API.

Your files are processed on your own server.

curl -o out.pdf --data-binary @in.pdf \
  'http://localhost:8080/api/compress?preset=high'

See SELF-HOSTING.md for the complete API, configuration options, and deployment notes.

Browser (WebAssembly)

The web/ directory contains a complete browser build.

The engine is compiled to WebAssembly and runs locally in the browser. Files are not uploaded, and the build makes is air gapped by default.

The same WebAssembly build is on npm as hyper-compress-wasm, a buffer-based SDK for platforms the native package does not cover:

import { compress } from 'hyper-compress-wasm';

const result = await compress(pdfBytes, { preset: 'medium' });

node wasm/verify.mjs some.pdf

This verifies that the WebAssembly output is byte-identical to the native build.

C API

sdk/native exposes a small C ABI:

• hpdf_compress_file
• hpdf_compress_buffer
• hpdf_last_error

The shared library exports only these symbols, and the ABI is additive only within a major version.

Compression Levels

Every option behind these presets is also available individually.

You can create custom profiles using image quality and resolution, grayscale conversion, colour reduction, font subsetting and unembedding, metadata and annotation stripping, PDF 2.0 Brotli streams, and page rasterisation for image-only documents.

What the Engine Does

Depending on the document and selected options, the engine can:

• re encode images with jpegli
• downsample images above a configured resolution ceiling
• choose between JPEG, JPEG 2000, Flate, CCITT, and JBIG2 on a per image basis
• convert Type 1 fonts to CFF
• subset embedded fonts to the glyphs actually used
• merge duplicate font programs
• unembed fonts that are metric-compatible clones of the standard 14 fonts
• regenerate content streams with correct handling for CMYK, CalRGB, Lab, ICCBased, Separation, DeviceN, Indexed, and pattern fills
• deduplicate identical objects and prune unused resources
• flatten ICC profiles
• remove selected metadata
• optionally apply PDF 2.0 Brotli stream compression
• optionally rasterise pages when the document is genuinely image-only

The engine applies multiple techniques mentioned above to achieve best possible compression.

Building from Source

The JavaScript parts require Node 22:

npm ci

make check

The native engine builds against a pinned PDFium checkout. The initial bootstrap is several gigabytes.

See BUILDING.md for complete instructions, the patch inventory, and platform-specific notes.

Testing

make check                      # typecheck, lint, unit and integration tests

make regress                    # regression failset, every preset

make bench CORPUS=path/to/dir   # benchmark harness from comparison.md

make fuzz                       # libFuzzer harness

make regress is the gate for bug fixes.

Every PDF in tests/regression/failset/ represents a file that previously exposed a bug. The suite checks validity, pixel fidelity, and text-layer survival across every relevant preset.

A clean run reports zero failing pairs.

Fuzzing runs through ClusterFuzzLite on every pull request that touches the engine, and again nightly for a longer session. Discovered crashes are pinned as regression seeds.

Licensing

Hyper Compress is licensed under the GNU AGPL v3.

If you need to use Hyper Compress in a proprietary or closed-source product, commercial licenses are available as annual subscriptions from $99/year, under the Hyper Compress Commercial License. For OEM terms, contact us at [email protected].

Bundled third-party components retain their own licenses. See NOTICE.md for the full list.

Contributing

Contributions are welcome.

Before opening your first pull request, there are two things to know:

1. Contributors need to sign the Contributor License Agreement. The bot will prompt you automatically.
2. Bug fixes should include the PDF that reproduces the issue so it can be added to the regression suite.

See CONTRIBUTING.md for the full contribution guide.

For security vulnerabilities, please see SECURITY.md.