1. 🚀 High Performance
With parallel processing and other optimizations, SoPDF significantly outperforms alternatives: rendering up to 2.82x faster, plain text extraction 2.74x faster, and full-text search 3.17x 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.
Measured on Apple M-series (arm64, 10-core), Python 3.12, against a 50-page PDF fixture. Run the suite yourself:
python tests/benchmark/run_benchmarks.py
| Scenario | SoPDF | PyMuPDF | Speedup |
|---|---|---|---|
| Open document | 0.1 ms | 0.2 ms | 1.93× faster |
| Render 1 page @ 72 DPI | 4.4 ms | 9.2 ms | 2.09× faster |
| Render 1 page @ 150 DPI | 11.7 ms | 30.5 ms | 2.61× faster |
| Render 1 page @ 300 DPI | 34.1 ms | 96.0 ms | 2.82× faster |
| 50 pages sequential @ 150 DPI | 546 ms | 1423 ms | 2.61× faster |
| 50 pages parallel @ 150 DPI | 419 ms | 437 ms | 1.04× faster |
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 1481 ms (slower than sequential) because MuPDF serialises concurrent renders behind a global lock.
| Scenario | SoPDF | PyMuPDF | Speedup |
|---|---|---|---|
| Plain text — 50 pages | 25.0 ms | 68.7 ms | 2.74× faster |
| Text blocks — 50 pages | 61.1 ms | 69.6 ms | 1.14× faster |
| Search 'benchmark' — 50 pages | 28.2 ms | 89.4 ms | 3.17× faster |
| Region extract — 50 pages | 26.5 ms | 38.3 ms | 1.44× faster |
Text search is the standout: 3.17× faster than PyMuPDF. Plain-text extraction follows at 2.74×. Correctness is verified — sopdf and PyMuPDF produce 99% word-level overlap on the same document, so the speed advantage carries no accuracy trade-off.
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.
pip install sopdfRequires 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")| Capability | Examples |
|---|---|
| Open from path / bytes / stream | 01_open |
| Render pages to PNG / JPEG | 02_render |
| Batch & parallel rendering | 02_render |
| Extract plain text | 03_extract_text |
| Extract text with bounding boxes | 03_extract_text |
| Full-text search with hit rects | 04_search_text |
| Split pages into new document | 05_split |
| Merge multiple PDFs | 06_merge |
| Save with compression | 07_save_compress |
| Serialise to bytes (no disk write) | 07_save_compress |
| Rotate pages | 08_rotate |
| Open & save encrypted PDFs | 09_decrypt |
| Auto-repair corrupted PDFs | 10_repair |
| Read & write document metadata | 11_metadata |
| Read document outline (TOC) | 12_outline |
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.
