natural-pdf 0.5.4

A more intuitive interface for working with PDFs

Natural PDF

A friendly library for working with PDFs, built on top of pdfplumber.

Natural PDF lets you find and extract content from PDFs using simple code that makes sense.

• Complete documentation here
• Live demos here

Installation

pip install natural-pdf

Need OCR, layout models, or other add-ons? Install what you need:

pip install easyocr                 # EasyOCR engine
pip install "natural-pdf[paddle]"   # PaddleOCR stack
pip install "surya-ocr<0.15"         # Surya OCR engine
pip install doclayout_yolo          # YOLO layout detection
pip install "natural-pdf[export]"   # PDF export, deskew
pip install "natural-pdf[all]"      # Everything

More details in the installation guide.

Quick Start

from natural_pdf import PDF

# Open a PDF
pdf = PDF('https://github.com/jsoma/natural-pdf/raw/refs/heads/main/pdfs/01-practice.pdf')
page = pdf.pages[0]

# Extract all of the text on the page
page.extract_text()

# Find elements using CSS-like selectors
heading = page.find('text:contains("Summary"):bold')

# Extract content below the heading
content = heading.below().extract_text()

# Examine all the bold text on the page
page.find_all('text:bold').show()

# Exclude parts of the page from selectors/extractors
header = page.find('text:contains("CONFIDENTIAL")').above()
footer = page.find_all('line')[-1].below()
page.add_exclusion(header)
page.add_exclusion(footer)

# Extract clean text from the page ignoring exclusions
clean_text = page.extract_text()

And as a fun bonus, page.viewer() will provide an interactive method to explore the PDF.

Key Features

Natural PDF offers a range of features for working with PDFs:

• CSS-like Selectors: Find elements using intuitive query strings (page.find('text:bold')).
• Spatial Navigation: Select content relative to other elements (heading.below(), element.select_until(...)).
• Text & Table Extraction: Get clean text or structured table data, automatically handling exclusions.
• OCR Integration: Extract text from scanned documents using engines like EasyOCR, PaddleOCR, or Surya.
• Layout Analysis: Detect document structures (titles, paragraphs, tables) using various engines (e.g., YOLO, Paddle, LLM via API).
• Document QA: Ask natural language questions about your document's content.
• Semantic Search: Index PDFs and find relevant pages or documents based on semantic meaning using Haystack.
• Visual Debugging: Highlight elements and use an interactive viewer or save images to understand your selections.

Learn More

Dive deeper into the features and explore advanced usage in the Complete Documentation.

Extending Natural PDF

Natural PDF now exposes its pluggable engines through small helper functions so you rarely have to touch the core registry directly. Two handy entry points:

from natural_pdf.tables import register_table_function

def table_delim(region, *, context=None, **kwargs):
    # return a TableResult or list-of-lists
    ...

register_table_function("table_delim", table_delim)

from natural_pdf.selectors import register_selector_engine

class DebugSelectorEngine:
    def query(self, *, context, selector, options):
        ...

register_selector_engine("debug", lambda **_: DebugSelectorEngine())

Best friends

Natural PDF sits on top of a lot of fantastic tools and mdoels, some of which are:

• pdfplumber
• EasyOCR
• PaddleOCR
• Surya
• A specific YOLO
• doctr
• docling
• Hugging Face