Skip to content
PDF Oxide

Migrate from pdfplumber to PDF Oxide

A complete guide to switching from pdfplumber to PDF Oxide, covering every API you use today and how to replace it.

Why Switch from pdfplumber?

There are four compelling reasons to migrate:

  1. 29x faster — PDF Oxide averages 0.8ms per page vs pdfplumber’s 23.2ms. A 100-page document processes in 80ms instead of 2.3 seconds.
  2. Encrypted PDF support — pdfplumber cannot open encrypted PDFs at all. PDF Oxide handles all encryption methods transparently, including AES-256.
  3. Image extraction — pdfplumber has no image extraction capability. PDF Oxide extracts embedded images in a single call.
  4. Markdown output — pdfplumber returns tables as Python lists that need manual formatting. PDF Oxide outputs structured Markdown with tables preserved, ready for LLM consumption.

Step 1: Install

pip install pdf_oxide
pip uninstall pdfplumber  # optional

Step 2: Replace Imports

# Before
import pdfplumber

# After
from pdf_oxide import PdfDocument

Step 3: API Mapping

Task pdfplumber PDF Oxide
Open PDF pdfplumber.open("file.pdf") PdfDocument("file.pdf")
Page count len(pdf.pages) doc.page_count()
Extract text pdf.pages[0].extract_text() doc.extract_text(0)
Character positions pdf.pages[0].chars doc.extract_chars(0)
Extract tables pdf.pages[0].extract_tables() doc.to_markdown(0)
Form fields Not supported (read-only) doc.get_form_fields()
Encrypted PDF Not supported PdfDocument("f.pdf", password="pw")
Extract images Not supported doc.extract_images(0)
To Markdown Not supported doc.to_markdown(0)
Render Not supported doc.render_page(0)
OCR Not supported doc.extract_text_ocr(0)
Create PDF Not supported Pdf.from_markdown("# Title")

Step 4: Common Pattern Changes

Text Extraction

pdfplumber requires a context manager. PDF Oxide does not:

# pdfplumber — context manager required
import pdfplumber
with pdfplumber.open("report.pdf") as pdf:
    for page in pdf.pages:
        text = page.extract_text()
        print(text)

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

Table Extraction

pdfplumber returns tables as nested Python lists. PDF Oxide outputs them as Markdown:

# pdfplumber — returns list of lists
import pdfplumber
with pdfplumber.open("report.pdf") as pdf:
    tables = pdf.pages[0].extract_tables()
    for table in tables:
        for row in table:
            print(row)

# PDF Oxide — structured Markdown output
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
md = doc.to_markdown(0)
print(md)  # Tables rendered as Markdown tables

Character-Level Extraction

# pdfplumber
import pdfplumber
with pdfplumber.open("report.pdf") as pdf:
    chars = pdf.pages[0].chars
    for c in chars:
        print(f"{c['text']} at ({c['x0']}, {c['top']})")

# PDF Oxide
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
chars = doc.extract_chars(0)
for c in chars:
    print(f"{c.char} at ({c.x}, {c.y})")

Encrypted PDFs (New Capability)

pdfplumber cannot open encrypted PDFs. PDF Oxide handles them transparently:

from pdf_oxide import PdfDocument

# Works with any encryption method, including AES-256
doc = PdfDocument("encrypted.pdf", password="password")
text = doc.extract_text(0)
print(text)

Image Extraction (New Capability)

pdfplumber has no image extraction. PDF Oxide makes it simple:

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"])

OCR for Scanned Documents (New Capability)

pdfplumber cannot handle scanned PDFs. PDF Oxide includes built-in OCR:

from pdf_oxide import PdfDocument

doc = PdfDocument("scanned.pdf")
text = doc.extract_text_ocr(0)
print(text)

Key Differences

  1. No context manager needed — pdfplumber uses with pdfplumber.open(...) as pdf:. PDF Oxide does not require a context manager.
  2. Encrypted PDFs — pdfplumber cannot open them at all. PDF Oxide handles encryption transparently.
  3. Tables — pdfplumber returns Python lists. PDF Oxide outputs tables as Markdown or HTML. For complex tables with visual debugging, you may want to keep pdfplumber alongside PDF Oxide.

Step 5: Testing Your Migration

Run your existing test files through both libraries and compare output:

from pdf_oxide import PdfDocument

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

# Verify text extraction
text = doc.extract_text(0)
print(text[:500])

# Verify page count
print(f"Pages: {doc.page_count()}")

# Verify form fields (if applicable)
fields = doc.get_form_fields()
for f in fields:
    print(f"{f.name}: {f.value}")

Other Migration Guides