pip install sopdf

Why SoPDF?

1. 🚀 High Performance

With parallel processing and other optimizations, SoPDF significantly outperforms alternatives: rendering up to 2.78x faster, plain text extraction 2.7x faster, and full-text search 3x faster — while maintaining 99% word-level accuracy consistency with PyMuPDF. See the Performance Benchmark section, or run it yourself.

2. ✨ Feature-Rich

Built on pypdfium2 (Google PDFium, for rendering and text) and pikepdf (libqpdf, for structure and writing). SoPDF covers the entire workflow from rendering and text extraction to structural editing.

3. 🎯 Clean API

Intuition as documentation. You would have designed it the same way.

4. 🔓 Permissive License

In PDF processing, feature-rich + open source often comes with a license unfriendly to the open-source ecosystem. But SoPDF delivers equivalent core capabilities under the Apache 2.0 License — no strings attached, no license audit, zero friction. Embed it, ship it, fork it. It's yours.

If you find SoPDF helpful, please consider giving it a ⭐ Star — it really means a lot to us. Every star fuels our motivation to keep improving.

Benchmarks

Measured on Apple M-series (arm64, 10-core), Python 3.10, against a 50-page PDF fixture. Run the suite yourself: python tests/benchmark/run_benchmarks.py

Rendering vs PyMuPDF

SoPDF wins at every DPI — and the margin widens at higher resolutions. In parallel mode, SoPDF achieves a 1.30× speedup over its own sequential baseline (the gap narrows because sequential rendering is now much faster). PyMuPDF's thread-parallel path, on the other hand, actually regresses to 1510 ms (slower than sequential) because MuPDF serialises concurrent renders behind a global lock.

Text Extraction vs PyMuPDF

Text search is the standout: 3× faster than PyMuPDF. Plain-text extraction follows at 2.7×. Correctness is verified — sopdf and PyMuPDF produce 99% word-level overlap on the same document, so the speed advantage carries no accuracy trade-off.

Architecture

SoPDF runs two best-in-class C/C++ engines in tandem:

┌──────────────────────────────────────────┐
│               SoPDF Python API           │
├───────────────────┬──────────────────────┤
│   pypdfium2       │   pikepdf            │
│   (Google PDFium) │   (libqpdf)          │
│                   │                      │
│   • Rendering     │   • Structure reads  │
│   • Text extract  │   • All writes       │
│   • Search        │   • Save / compress  │
└───────────────────┴──────────────────────┘

A dirty-flag + hot-reload mechanism keeps the two engines in sync: when you write via pikepdf (e.g. rotate a page), the next read operation (e.g. render) automatically reserialises the document into pypdfium2 — zero manual sync required.

Files are opened with lazy loading / mmap — a 500 MB PDF opens in milliseconds and only the pages you actually access are loaded.

For image encoding, SoPDF uses OpenCV (opencv-python) rather than Pillow. OpenCV's zero-copy NumPy bridge with pypdfium2 delivers 1.6×–1.9× faster encoding than the Pillow path — see docs/en/RuntimeDependencyCompare.md for the full analysis and benchmark breakdown.

Quick Start

pip install sopdf

Requires Python 3.10+. All native dependencies (pypdfium2, pikepdf, opencv-python) ship pre-built wheels for macOS, Linux, and Windows — no compiler needed.

import sopdf

# --- Open ---
# from a file path (near-instant thanks to lazy loading & mmap)
with sopdf.open("document.pdf") as doc:

    # --- Render ---
    img_bytes = doc[0].render(dpi=150)            # PNG bytes
    doc[0].render_to_file("page0.png", dpi=300)   # write to disk

    # parallel rendering across all pages
    images = sopdf.render_pages(doc.pages, dpi=150, parallel=True)

    # --- Extract text ---
    text = doc[0].get_text()
    blocks = doc[0].get_text_blocks()             # list[TextBlock] with bounding boxes

    # --- Search ---
    hits = doc[0].search("invoice", match_case=False)   # list[Rect]

    # --- Split & merge ---
    new_doc = doc.split(pages=[0, 1, 2], output="chapter1.pdf")
    doc.split_each(output_dir="pages/")
    sopdf.merge(["intro.pdf", "body.pdf"], output="book.pdf")

    # --- Save ---
    doc.append(new_doc)
    doc.save("out.pdf", compress=True, garbage=True)
    raw = doc.to_bytes()                          # no disk write

    # --- Rotate ---
    doc[0].rotation = 90

    # --- Metadata ---
    print(doc.metadata.title)                  # read
    doc.metadata.title = "Updated Title"       # write
    print(doc.metadata.creation_datetime)      # parsed Python datetime

    # --- Outline (table of contents) ---
    for item in doc.outline.items:
        print(f"[p{item.page + 1}] {item.title}")
    flat = doc.outline.to_list()               # PyMuPDF-compatible flat list

# --- Encrypted PDFs ---
with sopdf.open("protected.pdf", password="hunter2") as doc:
    doc.save("unlocked.pdf")                      # encryption stripped on save

# --- Open from bytes / stream ---
with open("document.pdf", "rb") as f:
    with sopdf.open(stream=f.read()) as doc:
        print(doc.page_count)

# --- Auto-repair corrupted PDFs ---
with sopdf.open("corrupted.pdf") as doc:
    doc.save("repaired.pdf")

Features

License

Apache 2.0 — see LICENSE.

SoPDF is free to use in personal projects, commercial products, and open-source libraries. No licensing fees, no attribution requirements beyond the standard Apache 2.0 notice.

WeChat Group