pdf_oxide Python Tutorial - Complete Getting Started Guide

Mar 4, 2026

You’ve heard about pdf_oxide. It’s the fast new PDF library written in Rust. But the documentation is scattered and you just want to get started quickly. Let me show you what you need to know.

Installation

pip install pdf_oxide

That’s it. Wheels are available for Linux, macOS, and Windows. It supports Python 3.8 through 3.14.

Core API Overview

The main entry point is the PdfDocument class.

from pdf_oxide import PdfDocument

# Open a PDF
doc = PdfDocument("file.pdf")

# Basic properties
print(f"Pages: {doc.page_count}")
print(f"Version: {doc.version}")

The document object gives you access to everything you need.

Quick Start Example

Here’s a complete example that opens a PDF and extracts text:

from pdf_oxide import PdfDocument

# Open a PDF
doc = PdfDocument("example.pdf")

# Get basic info
print(f"Pages: {doc.page_count}")

# Extract text from first page
text = doc.extract_text(0)
print(text)

# Extract from all pages
for i in range(doc.page_count):
    page_text = doc.extract_text(i)
    # Process each page

Text Extraction Methods

You have three text extraction options depending on what you need.

Plain Text

from pdf_oxide import PdfDocument

doc = PdfDocument("report.pdf")
text = doc.extract_text(0)
print(text)

Use extract_text when you just need the text content.

Character-Level with Positions

from pdf_oxide import PdfDocument

doc = PdfDocument("invoice.pdf")
chars = doc.extract_chars(0)

for char in chars:
    print(f"'{char.char}' at ({char.x:.1f}, {char.y:.1f})")

Use extract_chars when you need character positions for layout-aware processing.

Markdown Format

from pdf_oxide import PdfDocument

doc = PdfDocument("report.pdf")
markdown = doc.to_markdown(0)
print(markdown)

Use to_markdown when you need structured output for further processing.

Image Extraction

from pdf_oxide import PdfDocument

doc = PdfDocument("catalog.pdf")
images = doc.extract_images(0)

for img in images:
    print(f"Image: {img.width}x{img.height}")
    # Save or process the image

Each image object contains dimensions and the image data.

Form Handling

pdf_oxide can read and write form fields.

from pdf_oxide import PdfDocument

doc = PdfDocument("application.pdf")

# Get all form fields
fields = doc.get_form_fields()
for field_name, field_value in fields.items():
    print(f"{field_name}: {field_value}")

# Set a field value
doc.set_form_field_value("full_name", "John Doe")
doc.set_form_field_value("email", "[email protected]")

# Save the modified PDF
doc.save("filled_application.pdf")

Password-Protected PDFs

from pdf_oxide import PdfDocument

doc = PdfDocument("secret.pdf")
if doc.authenticate("mypassword"):
    text = doc.extract_text(0)
    print(text)
else:
    print("Wrong password")

Alternatively, pass the password directly when opening:

from pdf_oxide import PdfDocument

doc = PdfDocument("secret.pdf", password="mypassword")
text = doc.extract_text(0)

All Extraction Methods

Here’s a summary of all extraction methods:

from pdf_oxide import PdfDocument

doc = PdfDocument("example.pdf")

# Text extraction
text = doc.extract_text(0)

# Character-level with positions
chars = doc.extract_chars(0)

# Text spans with font metadata
spans = doc.extract_spans(0)

# Image extraction
images = doc.extract_images(0)

# Markdown format
markdown = doc.to_markdown(0)

Document Properties

from pdf_oxide import PdfDocument

doc = PdfDocument("example.pdf")

print(f"Page count: {doc.page_count}")
print(f"PDF version: {doc.version}")
print(f"Is encrypted: {doc.is_encrypted}")
print(f"Is form: {doc.is_form}")

Which Method to Use

Method	Returns	Use Case
`extract_text(page)`	String	Quick text extraction
`extract_chars(page)`	Character objects	Layout-aware processing
`extract_spans(page)`	Text spans with metadata	Font and formatting info
`extract_images(page)`	Image objects	Image extraction
`to_markdown(page)`	Markdown string	Structured output

Start with extract_text. Move to more detailed methods only when you need the additional data.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 pdf_oxide Documentation
👨‍💻 pdf_oxide GitHub Repository

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!