flpdf
A Pure Rust PDF toolkit modeled on the qpdf
workflow. flpdf aims for writer-level parity with qpdf — its outputs are
continuously compared against qpdf reference outputs through a golden matrix
(see docs/qpdf-compat.md).
Workspace layout
This repository is a Cargo workspace with two crates:
| Crate | Path | Purpose |
|---|---|---|
flpdf |
crates/flpdf |
Core PDF reader / writer library. |
flpdf-cli |
crates/flpdf-cli |
CLI (flpdf binary) that wraps the library. |
Both crates are licensed under MIT OR Apache-2.0.
Building
The default build is Pure Rust; flpdf depends on flate2 without pinning a
backend, so cargo build resolves to flate2's default (miniz_oxide).
Choosing a DEFLATE backend (downstream consumers)
flpdf does not re-export flate2's backend features (zlib-rs, zlib,
zlib-ng, …) as its own features. A downstream crate that wants a specific
backend adds flate2 as a direct dependency and enables the feature there;
Cargo's feature unification applies it to flpdf's copy of flate2 too. This
follows the pattern that
krilla PR #390 settled on —
keeping the backend choice with the consumer avoids forcing a single
implementation on every downstream build.
# Pure Rust, faster than miniz_oxide, WASM-friendly.
[]
= "..."
= { = "1", = ["zlib-rs"] }
# System libz — matches qpdf's compress2() byte-for-byte.
[]
= "..."
= { = "1", = ["zlib"] }
[!TIP] Because
flate2here is a Cargo-feature knob rather than a crate you actuallyuse, tools likecargo-macheteandcargo-udepswill flag it as an unused dependency. Ignore it in yourCargo.toml:[] = ["flate2"] [] = ["flate2"]
qpdf-zlib-compat (internal parity feature)
The optional qpdf-zlib-compat feature on the flpdf crate pins flate2's
backend to classic libz (via libz-sys) for flpdf's own bytes-identical test
suite. It is used by the parity CI job only and is not intended for production
consumers — pick a backend via the pattern above instead.
CLI usage
Common subcommands (flpdf <subcommand> --help for full options):
The zlib-flate subcommand also ships as a standalone zlib-flate binary
alias. It accepts qpdf's -uncompress, -compress, and -compress=n forms.
Encrypted inputs are supported via --password, --password-file, and
--password-mode {auto,bytes,hex-bytes,unicode} (the unicode mode validates
UTF-8 and preserves the supplied bytes for V=5 R=5/R=6 handlers, matching qpdf
11.9.0). RC4-backed handlers and revision 5
encryption are gated behind --allow-weak-crypto.
--static-id, --min-version, --force-version, and the qpdf compatibility
flags (--compress-streams, --linearize-pass1) are accepted on rewrite
to keep qtest-style command lines parsing cleanly.
Library usage
use File;
use BufReader;
use ;
The crate is organized as a few small layers:
Pdf— parsed-but-lazy document handle (Pdf::openreads the trailer and cross-reference table;ObjectHandle::try_*accessors resolve objects on demand).Object,Dictionary,Stream,ObjectRef— the data model.pages,outline_object_helper— read-only traversal helpers that mirrorqpdf --show-pagesand--json-key=outlines.write_pdf/write_qdf— fresh full rewrite and qdf-style flat dump.job::QPDFJob::check— qpdf-compatible document validation and warning completion for CLI and library job consumers.
Errors flow through the unified Error enum and the crate-level Result
alias. See the rustdoc on crates/flpdf/src/lib.rs for the full API.
Examples
Runnable examples live in crates/flpdf/examples.
Each one is a small, self-contained program; run any of them with:
| Example | Description |
|---|---|
inspect |
Inspect and dump a PDF's basic structure end to end. |
extract_page |
Extract a single page (0-based) into a new minimal PDF. |
extract_pages |
Extract a non-contiguous selection (pages 1, 3, 5) into a new file. |
extract_first_5_pages |
Extract the first 5 pages of a document into a new file. |
list_form_fields |
List every interactive form field with its type and value. |
walk_outline |
Walk the document outline (bookmarks) as an indented tree. |
pull_attachments |
Pull every embedded attachment out of a document to disk. |
reorder_pages |
Reorder a document's pages (here: reverse them) and write the result. |
merge_pdfs |
Merge two PDFs, preserving fonts shared between the merged-in pages. |
splice_pages |
Splice pages from one document into another at a given index. |
qpdf compatibility
flpdf's writer-level outputs are compared against qpdf in two places:
- Golden matrix —
tests/golden/compat-matrix.md, one row per (fixture, flag) tuple and one column per comparator strategy. Regenerated withBLESS=1 cargo test -p flpdf-cli --test compat_matrix_baseline. - Decisions registry —
docs/qpdf-compat-decisions.mdrecords every deliberate divergence point so contributors can tell intentional gaps from incidental ones.
The full workflow lives in docs/qpdf-compat.md. When
your change re-blesses the matrix or the static-ID baseline, check the PR
template's "Compat matrix" section.
Contributing
See CONTRIBUTING.md for the contributor guide and
AGENTS.md / CLAUDE.md for AI-agent conventions.
Issue tracking uses beads; start with
bd ready to see available work.
License
Licensed under either of
- Apache License, Version 2.0
- MIT License
at your option.