Skip to content
PDF Oxide

Von PyMuPDF (fitz) zu PDF Oxide migrieren

Ein vollständiger Leitfaden für den Umstieg von PyMuPDF auf PDF Oxide. Jede API, die Sie heute nutzen, und wie Sie sie ersetzen.

Warum von PyMuPDF wechseln?

Vier überzeugende Gründe für die Migration:

  1. 5,8× schneller — PDF Oxide liegt im Schnitt bei 0,8 ms pro Seite gegenüber 4,6 ms bei PyMuPDF. Im Großen summiert sich das: Ein Stapel mit 1.000 Seiten ist in unter einer Sekunde durch statt in fünf.
  2. MIT-Lizenz — PyMuPDF steht unter AGPL: Jeder Code, der damit interagiert, muss ebenfalls offengelegt werden — oder Sie kaufen eine Kommerzlizenz. PDF Oxide ist MIT-lizenziert — überall einsetzbar, ohne Auflagen.
  3. 100 % Zuverlässigkeit — PDF Oxide besteht 100 % der PDF-Testsuite. PyMuPDF scheitert an 0,7 % der Dateien (99,3 % Erfolgsrate) — das entspricht etwa einem fehlerhaften Ergebnis pro 140 Dokumente.
  4. Eingebaute Funktionen — Markdown-Konvertierung, HTML-Ausgabe, OCR, XFA-Formularunterstützung und PDF-Rendering sind enthalten. PyMuPDF benötigt dafür Zusatzpakete (pymupdf4llm) oder externe Werkzeuge (Tesseract).

Schritt 1: Installation

pip install pdf_oxide
pip uninstall pymupdf  # optional — entfernen, sobald alles läuft

Schritt 2: Imports ersetzen

# Vorher
import fitz

# Nachher
from pdf_oxide import PdfDocument

Wenn Sie pymupdf4llm für die Markdown-Konvertierung genutzt haben, können Sie diese Abhängigkeit komplett streichen — PDF Oxide bringt Markdown nativ mit.

Schritt 3: API-Zuordnung

Aufgabe PyMuPDF PDF Oxide
PDF öffnen fitz.open("file.pdf") PdfDocument("file.pdf")
Seitenanzahl doc.page_count doc.page_count()
Text extrahieren doc[0].get_text() doc.extract_text(0)
Zeichenpositionen doc[0].get_text("dict") doc.extract_chars(0)
Bilder extrahieren doc[0].get_images() + doc.extract_image(xref) doc.extract_images(0)
Text suchen doc[0].search_for("query") doc.search_page(0, "query")
Formularfelder doc[0].widgets() oder doc.get_form_fields() doc.get_form_fields()
Verschlüsseltes PDF doc.authenticate("pw") PdfDocument("f.pdf", password="pw")
Nach Markdown pymupdf4llm.to_markdown("file.pdf") (separates Paket) doc.to_markdown(0) (integriert)
Nach HTML Nicht verfügbar doc.to_html(0)
PDF erstellen Manuell via insert_text() Pdf.from_markdown("# Titel")
Zu Bild rendern doc[0].get_pixmap() doc.render_page(0)
XFA-Formulare Nicht unterstützt doc.has_xfa()
OCR Tesseract erforderlich Integrierte PaddleOCR

Schritt 4: Häufige Musteränderungen

Textextraktions-Schleife

# PyMuPDF
import fitz
doc = fitz.open("report.pdf")
for page in doc:
    text = page.get_text()
    print(text)

# PDF Oxide
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
for i in range(doc.page_count()):
    text = doc.extract_text(i)
    print(text)

Bildextraktion

PyMuPDF benötigt einen mehrstufigen xref-Lookup. PDF Oxide erledigt das in einem einzigen Aufruf:

# PyMuPDF — mehrstufiger xref-Lookup
import fitz
doc = fitz.open("report.pdf")
page = doc[0]
for img in page.get_images():
    xref = img[0]
    base = doc.extract_image(xref)
    with open(f"img.{base['ext']}", "wb") as f:
        f.write(base["image"])

# PDF Oxide — ein Schritt
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
for i, img in enumerate(doc.extract_image_bytes(0)):
    with open(f"img_{i}.{img['format']}", "wb") as f:
        f.write(img["data"])

Verschlüsselte PDFs

PyMuPDF erfordert ein zweistufiges Muster: erst öffnen, dann authentifizieren. PDF Oxide unterstützt sowohl password= im Konstruktor als auch doc.authenticate() nach dem Öffnen:

# PyMuPDF
import fitz
doc = fitz.open("encrypted.pdf")
doc.authenticate("password")
text = doc[0].get_text()

# PDF Oxide — ein Schritt mit password=
from pdf_oxide import PdfDocument
doc = PdfDocument("encrypted.pdf", password="password")
text = doc.extract_text(0)

Markdown-Konvertierung

PyMuPDF verlangt das separate Paket pymupdf4llm. Bei PDF Oxide ist Markdown integriert:

# PyMuPDF — Zusatzpaket erforderlich
import pymupdf4llm
md = pymupdf4llm.to_markdown("report.pdf")

# PDF Oxide — integriert
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
md = doc.to_markdown(0)

Seiten rendern

# PyMuPDF
import fitz
doc = fitz.open("report.pdf")
pix = doc[0].get_pixmap()
pix.save("page.png")

# PDF Oxide
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
png_bytes = doc.render_page(0, dpi=150)
with open("page.png", "wb") as f:
    f.write(png_bytes)

Schritt 5: Migration testen

Lassen Sie Ihre bestehenden Testdateien durch beide Bibliotheken laufen und vergleichen Sie die Ausgabe:

from pdf_oxide import PdfDocument

doc = PdfDocument("your-test-file.pdf")

# Textextraktion prüfen
text = doc.extract_text(0)
print(text[:500])

# Seitenanzahl prüfen
print(f"Pages: {doc.page_count()}")

# Formularfelder prüfen (sofern vorhanden)
fields = doc.get_form_fields()
for f in fields:
    print(f"{f.name}: {f.value}")

Weitere Migrationsleitfäden

Verwandte Seiten