PDF 2.0 Rust library
A reader and writer for PDF 1.x and PDF 2.0 (ISO 32000-2). No unsafe, no C
dependencies, and the format is implemented in this crate rather than wrapped: the four dependencies (miniz_oxide, aes, cbc, sha2) only
supply DEFLATE and AES/SHA primitives, and everything else is core + alloc,
so the library also builds without a standard library.
Status
The gate is cargo test --workspace, cargo fmt --all --check and
cargo clippy --workspace --all-targets -- -D warnings; all three pass on every
commit.
Working today:
-
Classic cross-reference tables,
/Prevchains and incremental updates. -
Cross-reference streams (
/Type /XRefwith/Wand/Index), object streams (/ObjStm) and hybrid files (/XRefStm). -
Filters: FlateDecode (with PNG 10–15 and TIFF 2 predictors), LZWDecode, ASCIIHexDecode, ASCII85Decode and RunLengthDecode, including
/Filterand/DecodeParmsarrays and indirect/Length. -
Every base object type, parsed and re-serialized byte-for-byte.
-
The document model: catalog, page tree with inherited
/MediaBox,/CropBox,/Rotateand/Resources, page content streams, and XMP/Metadata. -
Content-stream interpretation and text extraction for simple fonts:
BT/ET,Tf,Td,TD,T*,TL,Tm,Tj,TJ,',", withStandardEncoding,WinAnsiEncodingand/Differencesarrays. Line breaks come from the positioning operators, spaces from the text itself or from wideTJadjustments; inline images are skipped. -
Lazy object fetching with a cache, and every malformed input reported as an
Errinstead of a panic —tests/robustness.rsopens every fixture from every truncation and from sampled mutations and exercises the whole read API on whatever still opens. -
Writing PDF 2.0 files:
Document::new()builds a document,add_pageappends pages,save()emits a%PDF-2.0header, a Flate-compressed/ObjStmfor non-stream objects, a compressed/Type /XRefcross-reference stream with recorded byte offsets, XMP/Metadataand notrailer/Infodictionaries. Files written by this crate are read back by it — the writer has no other proof, andtests/writer.rscompares the whole object graph. -
AES-256 encryption, read side:
/V 5 /R 6with the standard security handler. User and owner passwords are both accepted; strings, streams, object streams and XMP metadata are decrypted,/EncryptMetadatais honoured, and the/Permstamper check is verified. The legacy revisions are read too:/V 1,/V 2and/V 4(revisions 2–4, RC4 and AES-128-CBC), with the per-object keys, the owner-password path and the/IDthey derive from./R 5is refused: it is the deprecated draft of revision 6. -
PDF 1.x as well as 2.0: the header gate accepts both (
%PDF-1.4–%PDF-2.x), and a committed corpus of 23 real files measures what that means: 23 parse and render, 21 are fully readable (cargo xtask corpus,docs/CORPUS.md).
Compared with
The honest version, including the column where we lose. Detail, sources and
check dates: docs/COMPETITORS.md; what each gap would
cost: docs/GAPS.md; how claims are checked:
docs/PROOF.md; what is shipped, scheduled, refused or
unplanned, feature by feature: docs/FEATURES.md.
| this crate | hayro | pdfium-render | lopdf | |
|---|---|---|---|---|
| Shape | one crate and one model: read, extract, render in the sibling crate, write new | read + render, read-only by design | C library wrapped in Rust: read, edit, render, extract | edit and rewrite; no rendering or extraction |
| PDF 1.x and 2.0 | 1.x and 2.x | 1.x–2.0 in practice | 1.x–2.0 | 1.x–2.0 |
| Text extraction | simple and /ToUnicode composite fonts, reading order |
not offered | yes, through pdfium | not offered |
| Rendering | paths, curves, fills, strokes, clips, transforms, text, images; no image codecs, shadings, transparency | the strongest pure-Rust renderer: image codecs, shadings, transparency, 1 600+ visual tests | the strongest overall, being Chromium's engine | none |
| Editing an opened file | no: save() builds new documents only |
no, by design | yes | yes |
No C, no unsafe, no_std, wasm |
yes, with size budgets in CI | no | no | no |
| Licence | Unlicense OR MIT | Apache-2.0 | MIT/Apache-2.0 | MIT |
| Adoption (2026-11-14) | 1 664 downloads | 5 384 557 | 3 954 648 | 30 289 120 |
If you need the best possible rendering today, use hayro or pdfium. If you need
to edit a document, use lopdf. If you need the same model to read a file, say
what it contains, draw it and write it again — in one dependency, without C, and
in places a C library cannot go — that is the gap this crate is trying to fill,
and docs/ROADMAP-NEXT.md says how it closes.
Limits
Deliberately out of scope for the pdf2 library: rasterising (that is
crates/pdf2-render, which shares the same model), PDF/A conformance, RC4 and
AES-128, the Info dictionary, form filling, JavaScript, XFA and image codecs
(DCT, JPX, CCITT, JBIG2). A file that needs one of these is reported as an error
rather than silently misread, and docs/CORPUS.md counts how
often that happens on real files.
Known limits inside the supported surface:
- Text extraction: composite (Type0) fonts with a
/ToUnicodemap and an Identity encoding are read (codes split by the CMap's code space, CID widths from/Wand/DW); one predefined CJK CMap ships as data (Adobe-Japan190ms-RKSJ-H), so those pages extract their text, while any other CMap-encoded font is reported by the CMap name it needs — the data is generated (cargo xtask cmaps) and its size is recorded against the wasm budget; the upper half ofMacRomanEncodingis not decoded; glyph names outside the built-in table are skipped rather than guessed. Spaces are recognised from the text itself and from wideTJadjustments, not from glyph advance widths. - Encryption is read-only and revision 6 only; the writer always produces unencrypted files.
/Countin a page tree is treated as a hint and never trusted; pages are counted by walking.- No external validator (
qpdf,verapdf,mutool,gs) exists in the environment this was built in. Proof rests on committed fixtures, byte-exact round-trips and cross-checks against independent implementations (NIST SP 800-38A for AES-256-CBC,base64.a85encodefor ASCII85, a separate encoder for LZW, Python for the PNG predictors).
Features
| Feature | What it enables |
|---|---|
std (default) |
everything: the file-system helpers Document::open_path, open_path_with_password and save_to_path, and the std::io::Error conversion |
alloc |
the no_std build: core + alloc, no file system, no standard library |
Without std, Document::open(&[u8]) and the in-memory writer are the entry
points; everything the parser, filters, document model, text extraction and
AES-256 decryption need lives in core and alloc. CI builds both targets for
x86_64-unknown-linux-gnu and thumbv7em-none-eabihf.
WebAssembly is tested the same way: crates/pdf2-wasm-smoke builds a browser
module (wasm32-unknown-unknown) driven from Node through a small C ABI, and a
WASI binary (wasm32-wasip1) that reads a fixture through std::fs; CI runs
both and fails if their gzip size passes the budget in
docs/PERFORMANCE.md. The browser package is on npm as
pdf2-wasm (npm install pdf2-wasm, SLSA provenance), and the
demo runs it against a real file.
Rendering
crates/pdf2-render rasterises a page into RGBA8 with the library's own
tokenizer: paths and curves, fills (non-zero and even-odd), strokes with the
three cap styles, miter/round/bevel joins and the miter limit, dashes and dash
phases, clipping through q/Q, the cm transform, /MediaBox origins and
/Rotate quarter turns, text through simple-font encodings (embedded TrueType
via ttf-parser, a built-in base-14 fallback otherwise), and /Image XObjects
(DeviceGray/RGB/CMYK, /Indexed, /ICCBased, /Decode, nearest or bilinear
sampling).
Correctness is proven against arithmetic, not against the last render:
tests/fixtures/calibration.pdf holds six pages whose right pixels follow from
ISO 32000 — colour conversion, cap and join geometry, dash phases, the two fill
rules, a Bézier circle of known area, exact image block edges, /Decode
inversion, a rotated image, a shifted media box, a /Rotate page and text
scaling/spacing — and crates/pdf2-render/tests/calibration.rs asserts them.
docs/RENDERING.md maps each page to its clause and lists
what is still unimplemented. tests/fixtures/book.pdf is the human check: a page
of book prose in an embedded Crimson Text subset, with the font's own metrics. Golden images pin the output as a regression net:
Working on this repository
AGENTS.md is the rulebook: invariants, the pipeline, and the dual publish
model (crates.io and npm, with separate tag namespaces). The gate is one
command, and it is the same sequence the CI Gate job runs:
Lint levels live in [workspace.lints], so clippy failures show up in a plain
cargo build too; scripts/install-hooks.sh adds a pre-commit format check and
a pre-push gate. main is protected: changes land as pull requests whose eleven
CI checks must be green; releases are tags pushed at a merged commit.
Layout
The repository is a Cargo workspace: pdf2 is the root package (the library in
src/, its tests and fixtures in tests/), and the tools live under crates/.
crates/pdf2-cli is the first member; it installs a pdf2 binary.
| Module | Responsibility |
|---|---|
src/error.rs |
one Error enum, no panics in the read paths |
src/lexer.rs |
tokens: whitespace, comments, numbers, names, strings |
src/object.rs |
the object model and its serialization |
src/parser.rs |
objects and indirect objects, streams by /Length |
src/filter.rs |
stream filters and predictors |
src/document.rs |
cross-reference tables and streams, object fetching |
src/page.rs |
page tree, boxes, XMP metadata |
src/content.rs |
content streams and text extraction |
src/crypto.rs |
AES-256 revision 6 security handler |
src/writer.rs |
Document::new() … save() |
crates/pdf2-cli/src/main.rs |
the pdf2 command: info, argument parsing, exit codes |
crates/pdf2-render/src/ |
the rasteriser: canvas, geometry, paths, scanline fill, content walker, PNG |
crates/pdf2-bench/src/ |
the benchmark binary and baseline comparison |
Command line
The workspace also ships a CLI, installed from
pdf2-cli:
Every command takes --password <pw> for encrypted files and --json for
machine-readable output; exit codes are 0 (ok), 1 (bad command line) and 2
(unreadable file).
Usage
use ;
An encrypted file takes its password:
use Document;
Writing looks like this (also available as cargo run --example write):
use ;
Tests and fixtures
cargo test --workspace runs unit tests next to each module, integration tests
in tests/*.rs, doc-tests that compile the examples above, and the pdf2-cli
binary tests, which execute the built binary against the committed fixtures.
The fixtures in tests/fixtures/ are small, committed PDFs, each named after
the structure it proves — see tests/fixtures/README.md. Six are generated by
tests/fixtures/make_fixtures.py (offsets and zlib streams computed there), and
the encryption pair by cargo run --example make_encrypted_fixture, because no
external PDF tool is available to produce them. Both generators are deterministic:
re-running them reproduces every byte.
Benchmarks and the memory numbers live in crates/pdf2-bench, gated in CI
against docs/performance-baseline.json —
method, reference numbers and budgets are in
docs/PERFORMANCE.md.
tests/robustness.rs is the single corpus that opens every fixture from every
truncation, from sampled byte mutations and from single-byte deletions, and then
exercises pages, metadata, content decoding and text extraction on anything that
still opens.
CI and releases
Changes are listed in CHANGELOG.md.
.github/workflows/ci.yml runs the gate in this README's Status section on
stable, on beta and on the declared MSRV (1.87), builds the docs with warnings
denied, and packages the crate.
rust-toolchain.toml pins stable (with rustfmt and clippy) for local work.
The MSRV stays checkable with cargo +1.87 test, because an explicit
+toolchain argument outranks that file — which is also how CI names every
toolchain it uses.
Releases are published from .github/workflows/publish.yml on a v* tag using
crates.io trusted publishing —
OIDC, short-lived tokens, no secrets. See docs/RELEASING.md
for the one-time crates.io configuration and the tag-and-push flow.
The way from here to 1.0 — proof-of-use tools, no_std and wasm targets, a
rendering crate and a wasm package, with the gates between alpha, beta, rc and
1.0 — is planned in docs/ROADMAP.md. Upgrading from
0.2.0-alpha.1 needs nothing beyond the version bump, but the feature flags are
worth knowing: see docs/MIGRATING.md.
Compatibility policy
From 0.7.0-rc.1 the public API is frozen; 1.0.0 changes no signatures.
- Covered by semver: every public item of
pdf2(types, functions, trait implementations) and the file-format behaviour documented indocs/SPEC-MAP.md— the features listed under Status keep working for the documents they claim to support. - Not covered: rendering fidelity beyond the documented scope, benchmark numbers, the content of error messages, and anything listed under Limits or out of scope. Adding a new API item, a new filter, a new font case or a new document feature is a minor release; changing or removing one is a major release.
- The tools (
pdf2-cli,pdf2-render,pdf2-wasm) follow their own semver lines, starting at 1.0 alongside the library.
Legal
Dual-licensed under MIT or the UNLICENSE.