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 | Installing from PyPI, or building the wheel from source. |
| 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 pdfspine command-line tool. |
| 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.