pdfspine

An Apache-2.0-licensed, pure-Rust reimplementation of PyMuPDF (fitz), with PyO3 Python bindings.

🦴 Part of the spine family — framework-free backend engines, each the spine of a domain: zero framework lock-in, Protocol-ized seams, offline-capable. pdfspine is the PDF spine (this repo); ragspine is the RAG spine (deterministic dual-channel retrieval + agent orchestration).

🤖 For AI agents / LLMs: before using this library, read llms.txt (concise index) and python/pdfspine/_llms/docs/ (full API / recipes / gotchas); after pip install they ship at site-packages/pdfspine/_llms/.

Status: alpha / pre-1.0, but the core is feature-complete. pdfspine can already parse/repair/decrypt PDFs, extract text & tables, search, edit / merge / split / save (incl. byte-exact incremental), encrypt, annotate, fill & flatten forms, redact (destructively), open image files as documents, render pages to images, and OCR (Tesseract + a pure-Rust PaddleOCR engine, stronger on CJK). 91.4% (703 / 769) of the PyMuPDF 1.24 public API is implemented and tested in the current local source. Published v0.9.1 covers 91.4% (703 / 769). The named 2026-09-11 local paragraph-dash full gate passed 2,034 Rust + 1,535 Python tests (68 existing Python skips). See validation baselines for exact source and binary identities. In the dated 58-document benchmark, its aggregate mean text scores trail fitz by 0.2–1.4 percentage points (and it beats fitz on Arabic / RTL); rendering is at/near parity (SSIM 0.984 mean, 2026-06-21) though about 1.3× slower than fitz (11.40 vs 8.93 ms, conformance/BENCH.md, 2026-09-05), and the pure-Rust PaddleOCR engine beats fitz on CJK scans (see Accuracy). Now on PyPI: pip install pdfspine (see Install); or build from source.

Spine 家族 / Spine family

本仓库是 Spine 家族的成员之一（角色：L1 引擎（含 pdf-typeset / pdf-fonts 被 git dep））。家族全部成员、分层、依赖方向、依赖形式与当前差距见 docs/spine-family.md；该文件在每个家族仓库中的副本内容相同，真源在家族根目录 ~/startup/spine/docs/spine-family.md，用根目录 make family-doc-sync 同步。

Why pdfspine?

PyMuPDF is excellent, but it is AGPL-3.0 (or a commercial license from Artifex) — a non-starter for many closed-source products, SaaS backends, and permissively-licensed open-source projects.

pdfspine is a drop-in-shaped, permissively-licensed (Apache-2.0) alternative:

• Apache-2.0 throughout — permissive, with an explicit patent grant. The dependency graph is gated by cargo-deny to exclude GPL / AGPL / LGPL / MPL / SSPL from the shipped wheel. License cleanliness is CI-enforced, not a promise.
• Pure Rust, no C blob. Self-contained wheels, no system zlib/C linkage, no bundled prebuilt engine (the differentiator vs pdfium-based wrappers).
• import fitz compatible (opt-in). A compatibility shim lets much existing PyMuPDF code run unmodified — available as import pdfspine.fitz as fitz, or registered under the global fitz / pymupdf names with one call to pdfspine.install_fitz_shim(). A default install is collision-safe: it does not claim those global names, so it coexists with a real PyMuPDF in the same environment. A machine-readable COMPAT.toml documents every symbol's status.
• Memory-safe by construction. #![forbid(unsafe_code)] in every first-party crate except the single audited PyO3 FFI chokepoint.
• Clean-room. No code, tests, or fixtures derived from MuPDF / PyMuPDF / any AGPL source.

What works today

Planned next: reading-order residuals, Type0/Type3 glyph-rendering edges, broader CJK coverage. See PRD.md / docs/ROADMAP.md. Out of scope: digital-signature creation.

Glyph geometry

The structured dict / rawdict / json / rawjson formats expose span matrix, text_matrix, ctm, dir, quad, seq, declared_size, and rendered_size; raw characters also expose matrix, quad, rendered_size, seq, and synthetic. The first glyph determines span["size"]; it equals span["rendered_size"] and sqrt(abs(det(matrix))), while declared_size preserves the signed PDF Tf operand. Use each raw character's rendered_size when glyph sizes vary.

matrix / quad use the page's device space, while text_matrix / ctm remain in PDF user space. HTML / XHTML / XML and get_texttrace() retain their existing declared-size semantics, and rotated-page coordinates and geometry-aware span boundaries can differ from PyMuPDF. See the text extraction guide for the field contract and the geometry, size parity, span parity, and performance reports for the measured limits and cost.

Install

pip install pdfspine

pdfspine is on PyPI. OCR works out of the box: the PP-OCRv5 weights ship in the shared ocrspine-models data package — a runtime dependency pip pulls in automatically — so the wheel itself stays lean and no longer embeds them. To build from source instead, see Build & install.

Python 3.12+ is supported. Prebuilt wheels are published for Linux x86-64 / ARM64, macOS Intel / Apple silicon, and Windows x86-64; an sdist is also available for other supported environments.

Quick start

import pdfspine

doc = pdfspine.open("input.pdf")
print(len(doc), "pages", doc.metadata)

page = doc[0]
print(page.get_text())                       # plain text
print(page.search_for("invoice"))            # list[Rect]
page.get_pixmap(dpi=150).save("page1.png")   # render to image

tables = page.find_tables()
for t in tables.tables:
    print(t.to_markdown())                    # or t.to_html() for merged cells

# Optional: pip install "pdfspine[tatr]", then prefetch the pinned checkpoints.
# vision_tables = page.find_tables(strategy="vision", backend="tatr")

doc.save("output.pdf", garbage=4, deflate=True)
doc.save_html("output.html")                 # complete UTF-8 HTML5 document
md = doc.to_markdown()                       # PDF → Markdown (pdfspine extension)
doc.save_markdown("output.md")               # UTF-8 Markdown for RAG / LLM

# Markdown → PDF (pdfspine original extension — not part of the PyMuPDF surface)
pdfspine.markdown_to_pdf("# Title\n\nHello **Markdown**!").save("hello.pdf")

Existing PyMuPDF code often runs unchanged via the opt-in compat shim:

import pdfspine.fitz as fitz                  # the shim, no global-name collision
doc = fitz.open("input.pdf")
text = doc[0].get_text("dict")

# Or make the literal `import fitz` resolve to the shim (one-time opt-in):
import pdfspine
pdfspine.install_fitz_shim()
import fitz                                    # now -> pdfspine's fitz shim

A default install does not claim the global fitz / pymupdf names, so it is safe alongside a real PyMuPDF; install_fitz_shim() uses setdefault and never clobbers a PyMuPDF you imported first.

Command line:

pdfspine info report.pdf
pdfspine text report.pdf --pages 1-3 --format json -o out.json
pdfspine render report.pdf --dpi 200 -o images/
pdfspine merge a.pdf b.pdf -o merged.pdf

Accuracy

Validated against an objective ground-truth harness and with PyMuPDF (fitz) as the differential oracle (clean-room: the AGPL oracle is run locally only and never committed). See docs/BENCHMARKS.md and the conformance/gt/ reports for the dated, reproducible evidence.

• In the dated 58-document benchmark, pdfspine's aggregate mean edit-similarity, token-F1, word-set-Jaccard, and reading-order scores trail fitz by 0.2–1.4 percentage points. It reaches parity on selected born-digital metrics and beats fitz on Arabic / RTL (correct bidi reordering).
• Rendering is at/near parity with fitz (page-image SSIM 0.984 mean / 0.989 median over a 46-document sample, 2026-06-21). Speed, per the dated 2026-09-05 conformance/BENCH.md: open 1.3× and text extraction 2.3× faster than fitz; rendering about 1.3× slower (11.40 vs 8.93 ms per page at 150 dpi).
• OCR beats fitz on CJK scans: the pure-Rust PaddleOCR engine (PP-OCRv5, with weights from the shared ocrspine-models package) outperforms fitz's OCR path on Chinese/Japanese/Korean documents.
• Real-corpus robustness: open rate 100%, 0 panics/hangs, re-saved files 100% qpdf --check-clean across the public-domain US-government corpus.

Remaining accuracy work (reading-order residuals, Type0/Type3 glyph-rendering edges, broader CJK) is tracked in docs/PRD-NEXT.md.

Build & install

Requirements: Rust (pinned to 1.96.0 by rust-toolchain.toml), Python ≥ 3.12, maturin ≥ 1.12,<2. uv recommended.

uv venv .venv && source .venv/bin/activate
maturin develop                 # build + install the extension in-place
python -c "import pdfspine; print(pdfspine.__version__)"
# redistributable wheel:
maturin build --release         # -> target/wheels/

Building from source needs a C/asm compiler. The bundled pure-Rust PaddleOCR engine depends on tract, which compiles target-specific assembly kernels at build time: a C compiler (cc/clang) on Linux/macOS, or the MSVC Build Tools (incl. ml64.exe) on Windows. Prebuilt PyPI wheels need none of this. To build a fully C-free library, compile the Rust crates with --no-default-features (drops the paddle-ocr feature). The wheel no longer embeds the OCR models — they ship in the shared ocrspine-models package (a runtime dependency).

Architecture

A Cargo workspace with a strict dependency DAG; the Python bindings touch exactly one façade crate, and core logic is split into independently testable units.

                  py-bindings   (PyO3 cdylib -> pdfspine._core, abi3-py311)
                       │
                       ▼
                    pdf-api      facade / re-exports
        ┌──────────┬───┴────┬──────────┐
        ▼          ▼        ▼          ▼
    pdf-text   pdf-edit  pdf-image  pdf-render
        │          │        │          │
        └────┬─────┘        │     (fonts, text)
             ▼              │
         pdf-fonts ◄────────┘
             ▼
         pdf-core   ◄────────  pdf-crypto

Develop / test

./ci.sh                                      # complete local/CI/pre-push gate
# Individual focused checks remain available:
python scripts/quality_gate.py --help
python conformance/run_validation.py …       # real-corpus accuracy harness

The gate runs rust → extension → python → drift → artifacts. The extension phase fingerprints the Rust inputs (crates/**, Cargo.toml, Cargo.lock, pyproject.toml, rust-toolchain*) against .gate/extension.stamp and re-runs maturin develop --release when they differ, so pytest never runs against a stale _core. Skip it with --skip-extension-check or PDFSPINE_GATE_SKIP_EXTENSION=1.

pdfspine is built strictly test-first (red → green → refactor → harden); the per-function test plan is in docs/test-case-catalog.md.

Documentation

Guide + API reference + PyMuPDF migration guide: build the docs site with mkdocs serve (see mkdocs.yml / docs/). The authoritative design lives in PRD.md.

License

Apache-2.0 — see LICENSE and NOTICE. All third-party dependencies are permissive (MIT / Apache-2.0 / BSD / Zlib / …); the shipped graph is CI-verified free of copyleft.