cheap-route

<img src="docs/assets/logo.svg" width="120" alt="gpress">

<h1 align="center">gpress</h1>

<em>Lossless PDF compression: smaller PDFs that standard readers open,<br>and an archive that restores byte for byte.</em>

<a href="https://github.com/soumyadebroy3/gpress/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/soumyadebroy3/gpress/ci.yml?branch=main&style=flat-square&label=CI&color=111111" alt="CI"></a> <a href="https://github.com/soumyadebroy3/gpress/actions/workflows/codeql.yml"><img src="https://img.shields.io/github/actions/workflow/status/soumyadebroy3/gpress/codeql.yml?branch=main&style=flat-square&label=CodeQL&color=111111" alt="CodeQL"></a> <img src="https://img.shields.io/badge/version-0.1.0-111111?style=flat-square" alt="Version 0.1.0"> <img src="https://img.shields.io/badge/archive%20format-9-111111?style=flat-square" alt="Archive format 9"> <img src="https://img.shields.io/badge/Rust%20%C2%B7%20C%20%C2%B7%20WebAssembly-111111?style=flat-square" alt="Rust, C and WebAssembly"> <a href="#licence"><img src="https://img.shields.io/badge/licence-MIT%20OR%20Apache--2.0-111111?style=flat-square" alt="Licence: MIT OR Apache-2.0"></a>

<a href="#benchmarks"><img src="docs/assets/hero.svg" width="880" alt="gpress archive: 60.9% of the original size on 907 public test PDFs, against 76.3% for the best of xz, Brotli and Zstandard. Normal PDF: 85.0% of the input on the 90 files gpress rewrites from a hard 120-file sample, against 87.2% for qpdf 11.9.0 at its strongest lossless setting. Web module: 268 KB of gzipped WebAssembly for normal PDFs, 383 KB with the archive, the same output as the native library."></a>

<strong>Archives about 20% smaller than the best of xz, Brotli and Zstandard</strong><br> <strong>Normal PDFs 2.5% smaller in total than qpdf 11.9.0's strongest lossless output, on the files gpress rewrites</strong><br> <strong>Every effort level lossless &middot; 268 KB gzipped in the browser for normal PDFs, 383 KB with the archive</strong><br> _{Archive: 907 public test PDFs, format 9, effort 100, built with Lepton. Normal PDF: totals on the 90 files gpress rewrites from a hard 120-file sample, default effort. One thread. Browser: the gzip sizes of the two WebAssembly modules, as recorded in bench/sizes.json on 2026-10-22, before archive format 9. <a href="#benchmarks">Details</a>.}

_{<a href="#quick-start">Quick start</a> &middot; <a href="#install">Install</a> &middot; <a href="#use-it-from-code">From code</a> &middot; <a href="#benchmarks">Benchmarks</a> &middot; <a href="docs/reference.md">Reference</a> &middot; <a href="SECURITY.md">Security</a>}

gpress is a library written in Rust, with C and WebAssembly bindings and a command-line tool. It makes two kinds of output, and checks each one before it returns it, except the archive's rare fallback and a file stored as it is (below).

[!IMPORTANT] Version 0.1.0, in active development: the API may still change, and nothing is published to crates.io or npm yet, so everything below builds from this repository. The archive format is version 9: archives from earlier development versions are refused, except one a format-8 build stored uncompressed, which still restores. CI builds and tests on Linux (x86-64).

Two outputs

Quick start

gpress optimize in.pdf out.pdf            # a smaller PDF that standard readers open
gpress optimize in.pdf out.pdf --quick    # the same at effort 0, the fast path
gpress pack in.pdf in.gpz                 # the gpress archive (works on any file)
gpress unpack in.gpz back.pdf             # the original, byte for byte

optimize prints one tab-separated line: the input, SMALLER or UNTOUCHED, bytes in, bytes out, seconds and the details. pack prints the input, bytes in, bytes out, seconds, then PACKED or STORED with the archive's statistics. For tests/data/format-v9.pdf, copied to in.pdf:

in.pdf	SMALLER	8791	4955	0.15	objects=6 streams=2 reencoded=2 kept=0 objstms=1 dropped=1 jpegs_retabled=0 fax_to_jbig2=0
in.pdf	8791	6963	0.10	PACKED streams=3 rebuilt=3 rebuilt_bytes=7909 lepton=0 type1=0 fax=0 decrypted=0 decoded_bytes=54664

A file optimize can't make smaller or can't safely touch (a signed file, PDF/A, a file with earlier revisions, an encrypted file that needs a password, a damaged one) is written to out.pdf unchanged, with UNTOUCHED and the reason.

gpress without arguments lists every option, and the engine's measuring commands (deflate, inflate, batch, jpeg, fax-decode, expand (it decodes streams; restoring an archive is unpack), ...) used for checks and benchmarks; the comments at the top of src/bin/gpress.rs name them. For optimize, pack and unpack the exit status is 0 when the call worked, 2 for a usage or file error, and otherwise the library's error code (for example 2 for a damaged archive, 6 when --time-budget ran out; the full list is in the same comments).

Install

You need a recent stable Rust (rustup); CI uses the latest stable release.

The command-line tool

cargo install --locked --git https://github.com/soumyadebroy3/gpress gpress

Add --features existing to also use Lepton (Apache-2.0) for JPEG streams in the archive. An archive with parts Lepton made restores only with such a build.

git clone https://github.com/soumyadebroy3/gpress
cd gpress
cargo build --release            # the tool is target/release/gpress

--features existing works here too.

[dependencies]
gpress = { git = "https://github.com/soumyadebroy3/gpress" }

cargo build --release -p gpress-c

This builds libgpress_c as a shared and a static library in target/release/ (libgpress_c.so and libgpress_c.a on Linux), with the header crates/gpress-c/include/gpress.h. On Linux:

cc -Icrates/gpress-c/include app.c target/release/libgpress_c.a -lpthread -ldl -lm -o app   # static
cc -Icrates/gpress-c/include app.c -Ltarget/release -lgpress_c -o app                      # shared: run it with
LD_LIBRARY_PATH=target/release ./app                                                         # the library on its path

rustup target add wasm32-unknown-unknown
cd crates/gpress-wasm/js
npm ci
npm run build                    # dist/: gpress.js, gpress.d.ts, gpress.wasm, gpress-web.wasm

The build runs binaryen's wasm-opt on the modules when it is on PATH; install binaryen for the smallest modules.

Effort levels

--effort N (the effort option) runs from 0, the fastest, to 100, the smallest; the default is 100. Every level is lossless: they differ only in how hard the engine searches, and every level's output is checked the same way. The output is the same for any thread count.

<img src="docs/assets/normal-pdf.svg" width="880" alt="Normal PDF, bytes saved on the 90 files gpress rewrites from a hard 120-file sample: gpress effort 100 15.0%, effort 50 14.8%, effort 0 13.0%; qpdf 11.9.0 at its strongest lossless setting 12.8%.">

CPU time is for the whole 120-file sample (bench/sets/sample120.txt, 78.3 MB, a deliberately hard mix of the slowest, the largest and random files) on one thread; output is the total size as a share of the input on the 90 files the engine rewrites. For qpdf it counts the 85 outputs bench/verify_pdf.py finds the same as their input apart from the trailer's /ID, and the other 5 files at their input size; its setting is --object-streams=generate --compress-streams=y --recompress-flate --compression-level=9 --decode-level=specialized. On the 118 files qpdf can open (it refused 2 encrypted files) the comparison turns around: qpdf rewrites each of them, dropping earlier revisions, unreferenced objects and whatever it cannot read, while gpress returns the files it can't safely touch unchanged. Counting those as they are, an earlier build (ca8fa92) gave 90.2% of the input at effort 100 on those 118 files, against 74.7% for qpdf with object streams and Flate at level 9. The first measurement (builds 52a91f0 and 20f8e69) was made in October 2026 for the change that added the fast path, on a 4-core 2.1 GHz Xeon virtual machine. Later changes made the strong encoder faster. Build 37bd3f3 was measured again at efforts 0, 50 and 100, and at each effort its outputs total exactly the first run's bytes. It ran on a machine about 1.2 times slower by the benchmark's calibration, so the two time columns compare only roughly. At those three efforts the current code gives the same outputs; its one later change on this path, the JBIG2 decoder that reads fax images back (717bf45), was not timed. The other levels were not measured again: their times and outputs are the first run's. Both runs, with their builds and calibrations, are in bench/RESULTS.md. In the archive, data that already looks compressed is coded plainly below effort 50. The reference has the details.

Use it from code

Rust

use gpress::{Options, Outcome};

let opt = Options::new().effort(80).threads(4);

// A smaller PDF that standard readers open.
let r = gpress::optimize(&pdf_bytes, &opt)?;
match r.outcome {
    Outcome::Smaller(_report) => std::fs::write("out.pdf", &r.data)?,
    Outcome::Untouched(why) => println!("left as it was: {why}"),
}

// The gpress archive, and the original back from it.
let archive = gpress::compress(&pdf_bytes, &opt)?;
let original = gpress::expand(&archive.data, &opt)?;
assert_eq!(original, pdf_bytes);

optimize, compress and expand each run inside a panic guard, so a bug that panics never reaches the caller: it comes back as an error, usually Error::Internal, or gpress takes its fallback (after a failed restore check, for example). In a build with panic = "abort", such as the WebAssembly module below, it aborts. The engine's own types, public too for measuring (reference), have no guard.

Errors are a plain Error enum with a stable numeric code and a message without internal paths:

Optimized.outcome says what happened: Smaller with a Report (objects, streams re-encoded and kept, object streams, JPEGs given new tables, fax images written as JBIG2, how the file is encrypted), or Untouched with the reason. Compressed carries the archive's statistics (streams rebuilt, through Lepton, Type 1 fonts opened, fax images, streams stored decrypted, decoded bytes, and stored when nothing could be made smaller).

gpress_options opt; gpress_options_default(&opt); opt.effort = 70;
gpress_result r = gpress_optimize(pdf, pdf_len, &opt);
if (r.code == GPRESS_OK) fwrite(r.output.data, 1, r.output.len, out);
else fprintf(stderr, "%s\n", r.message);
gpress_result_free(&r);

Every function is thread-safe and never reads outside the buffers it is given. It never aborts the process on bad input if the calling thread has enough stack (part of the work, which parses objects nested up to 256 deep by recursion, runs on that thread; a 128 KiB thread stack, musl's default, may be too small), and a bug that panics never reaches the host: the panic guard above applies. Like any Rust code it does abort if memory runs out, so set the size limits to what the host can afford. Every buffer it hands out is freed with gpress_result_free (or gpress_free / gpress_free_message, each given the field's address), which are safe on null and on a result already freed: a free clears what it freed, so freeing the same result twice, or a part before the whole result, is harmless by construction. An empty output is a null pointer with length 0. The options struct has the same fields as the Rust Options but store_budget, which stays at its default (fill it with gpress_options_default first; a size left at 0 means its default). crates/gpress-c/examples/roundtrip.c is a complete program, and bench/gpress_harness.c sends the security suite's hostile inputs through this API.

crates/gpress-wasm is a plain WebAssembly module (no bindgen layer) with a typed wrapper in js/gpress.ts:

import { Gpress } from "./dist/gpress.js";                         // built in crates/gpress-wasm/js; not on npm yet
const g = await Gpress.load(fetch("/gpress.wasm"));                 // or gpress-web.wasm: no archive, smaller
// In Node, pass a file URL (or a path from the working directory) instead:
// await Gpress.load(new URL("./dist/gpress.wasm", import.meta.url))
const smaller = g.optimize(bytes, { effort: 70, jbig2: false });   // { data, outcome, reason? }
const archive = g.compress(bytes);
const original = g.expand(archive.data, { maxLenMiB: 512 });       // throws GpressError on a damaged archive

The module gives the same bytes as the native library (the web module too, for optimize; see Building only what a product needs), is single-threaded and has no clock (so no time budget: run it in a Web Worker to keep a page responsive and to end it when it has taken too long). It is built with panic = "abort" (wasm32-unknown-unknown aborts on a panic anyway), so the panic guard that turns a bug into Error::Internal natively catches nothing there: a bug, or a failed memory growth in the engine, traps the module, and the wrapper turns the trap into a GpressError with code 4 and marks the instance dead (load a fresh one). Sizes are 32-bit inside it: the wrapper refuses inputs of 2 GiB and more. Pages with a Content Security Policy need 'wasm-unsafe-eval' in its script-src.

A first load compiles the module (4 to 9 ms in Node for the module of PR #8, bench/RESULTS.md, Start-up; CI's WebAssembly job measures it again in every run). Gpress.compile(source) returns the compiled module, and Gpress.load(module) makes an instance from it without compiling again: compile once, then make one instance per worker (a module can be posted to a Web Worker) or a fresh one after a trap. Serve the file as application/wasm, with no parameters, so that it compiles while it downloads (with any other type it is compiled once it has arrived).

Options

Everything a caller of optimize, compress and expand can tune is a field of Options, and every field is a flag of the command-line tool. The ones most callers need:

Every other option, the memory each limit bounds, the parts of the engine a build can leave out (--no-default-features --features ..., for example the smaller web build without the archive), how encrypted PDFs are handled and what each part of the engine does are in the reference.

Benchmarks

Measured on 907 public test PDFs (130.5 MB: the pdf.js, pypdf, OCRmyPDF and pikepdf test suites, many of them deliberately broken or unusual), fetched and pinned by bench/fetch_corpus.sh, and on a deliberately hard 120-file sample of them (bench/sets/sample120.txt, 78.3 MB).

<img src="docs/assets/archive.svg" width="880" alt="Archive size as a share of the original on 907 public test PDFs: gpress 60.9%; the best of Brotli 11, xz -9e and Zstandard 19 file by file 76.3%; Brotli 11 76.5%; xz -9e 76.8%; Zstandard 19 --long 77.0%.">

Every archive in those runs was restored by a separate process and compared byte for byte, and the competitors ran on the same files. All three rows are the current code: the archive rows are format 9, and the current code's normal-PDF outputs total exactly the bytes behind its row (see Effort levels, which also says how qpdf does when every file it opens is counted).

These come from the first full run (build d85cd7a), and bench/RESULTS.md says which build and machine each figure comes from. Later builds changed the normal-PDF output and the archive format, so they are not figures for the current code.

• Normal PDF on all 907 files, maximum effort: 16.0% smaller on the 697 files it rewrote; qpdf (object streams, Flate at level 9) made the same files 9.3% smaller. Every one of those 697 outputs was compared with its original by tools we didn't write: qpdf, pikepdf, PDFium, Poppler and pdf.js.
• Flate streams on their own, maximum effort (7,280 distinct streams from the test files, each decoding to at most 4 MiB): gpress 41.05 MB; Zopfli (15 iterations) 0.67% larger, libdeflate 12 1.40% larger, zlib 9 6.95% larger.

bench/benchmark.py measures any build.

Safety

• No data loss. Every transformation of a normal PDF is checked before it is used, and anything uncertain leaves that stream or file untouched. A damaged archive is refused with an error, or restored exactly when the damage misses what it needs; it is never restored wrongly.
• Untrusted input. Sizes are bounded by Options, by the file's own size or by a fixed limit, decoding stops when data runs out, nothing a file claims sizes memory on its own, and no call to optimize, compress or expand panics across the library boundary. What no option bounds yet: cross-reference streams decode as far as the file's size allows, the PDF/A check reads metadata up to 16 MiB, and objects parsed from object streams take more memory than the bytes the limits count (see max_stream in the reference).
• Deterministic. The same bytes for any thread count and with or without a time budget (tested); the archive's context-mixing model uses integer arithmetic only, its constants are fixed in code and never read from the environment, and the WebAssembly module is checked against the native library's bytes.
• Licences. Libraries under MIT, Apache-2.0, BSD, ISC, Zlib, Unicode or MPL-2.0 only (the licence rule): cargo deny checks every dependency's licence and the RustSec advisories in CI.

SECURITY.md has the threat model, the guarantees with where each is kept, how they are checked, and how to report a vulnerability privately.

What's inside

Most of the engine is our own code. The parts that follow another project's code (zlib, libdeflate, the LZMA SDK) say so and keep its licence notice, as listed in [Code from other projects