Overview
An orientation to pdfspine's two equivalent import styles and a map of where to go next in the guide.
This guide walks through using pdfspine for real work, from installation to the individual feature areas. Every code block uses the actual public API.
Two import styles
pdfspine ships two equivalent entry points:
import pdfspine # the native, idiomatic package
# or, the opt-in PyMuPDF compatibility shim:
import pdfspine.fitz as fitz # no global-name collisionBoth expose the same open(), Document, Page, Pixmap, and geometry
classes. Use import pdfspine for new code; for existing PyMuPDF code, the shim
is opt-in (a default install does not claim the global fitz / pymupdf names,
so it coexists with a real PyMuPDF). To make an unmodified import fitz resolve
to the shim, call pdfspine.install_fitz_shim() once at startup — see
Migrating from PyMuPDF.
Where to go next
| Page | What it covers |
|---|---|
| Installation | Building and installing the wheel (not yet on PyPI). |
| Quickstart | Open, extract, search, render, and save. |
| Text extraction | get_text variants, search_for, TextPage, tables. |
| Editing & saving | Merge / split, metadata, TOC, annotations, forms, redaction. |
| Rendering | get_pixmap, Pixmap, DisplayList, SVG. |
| Command-line interface | The planned pdfspine CLI. |
| Migrating from PyMuPDF | Compatibility mapping and gaps. |
| License | Apache-2.0, clean-room note, dependency licenses. |
pdfspine is pre-1.0 and under active development. The implemented surface is
substantial but accuracy validation against a real PDF corpus is ongoing.
Methods that are not yet implemented raise pdfspine.PdfUnsupportedError
with a hint, never a bare AttributeError.
Introduction
pdfspine is a permissively-licensed, pure-Rust reimplementation of PyMuPDF (fitz) with a Python API, an import fitz compatibility shim, and a command-line tool.
Installation
How to install pdfspine — the planned PyPI path and the current build-from-source flow with maturin, plus requirements and verification.