Installation

Requirements

• Python ≥ 3.12 for the published 0.11.2 package. Use a wheel matching your interpreter and platform; the earlier 3.11 installation floor no longer applies.
• Rust (pinned by rust-toolchain.toml) and maturin ≥ 1.12 — only needed to build from source.
• uv is recommended for managing the virtualenv, but any virtualenv tool works.

Install from PyPI

pdfspine is on PyPI:

pip install "pdfspine==0.11.2"

This provides the pdfspine (native) package from one wheel, plus the opt-in pdfspine.fitz / pdfspine.pymupdf compatibility submodules. By default it does not claim the global fitz / pymupdf import names, so it is collision-safe alongside a real PyMuPDF; call pdfspine.install_fitz_shim() to register them. OCR works out of the box: the PP-OCRv5 weights ship in the shared ocrspine-models data package, pulled in automatically as a runtime dependency.

Optional ONNX layout and tables

pip install "pdfspine[onnx]==0.11.2"

This installs the runtime dependencies, not layout/table weights. Supply the weights through PDFSPINE_ONNX_MODELS or explicit model paths; see layout and tables. These weights are separate from the shared OCR model package. Missing runtime or model files raise PdfUnsupportedError.

Build from source (alternative)

Clone the repository and check out the released source before building:

git clone https://github.com/VoldemortGin/pdfspine.git
cd pdfspine
git checkout 78a64d6e252ab739fcbad66c0d7f5328a080d667

# Create an isolated environment.
uv venv --python 3.12 .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

# Build the Rust extension and install it into the environment.
uv tool run --from "maturin>=1.12,<2" maturin develop --release --locked --uv

Then smoke-test the import:

python -c "import pdfspine; print(pdfspine.__version__)"

To build a redistributable wheel instead of installing in place:

uv tool run --from "maturin>=1.12,<2" maturin build --release --locked
# wheel lands in target/wheels/
uv pip install target/wheels/pdfspine-*.whl

Verify

import pdfspine

print(pdfspine.__version__)
print(pdfspine.version)           # version tuple from the Rust core

# The opt-in fitz compat shim works too:
import pdfspine.fitz as fitz
print(fitz.pymupdf_version)        # the PyMuPDF baseline this shim targets