How to Parse PDFs and Scans Into Clean JSON With Unstructured

November 7, 2026

Unstructured turns a PDF, DOCX, HTML page, or scanned image into a list of typed elements — Title, NarrativeText, Table, ListItem — as JSON. You run unstructured[all-docs] locally, or call the hosted API, then filter by element type before you chunk and embed.

That typing is the whole value. Naive PDF extraction gives you a wall of text with tables smeared into it. Unstructured keeps structure so downstream retrieval can skip headers, page numbers, and boilerplate.

What does Unstructured actually output?

Each partitioned document returns a JSON array. Every item has type, text, metadata (page number, coordinates, filename), and sometimes text_as_html for tables.

A typical page produces 15–40 elements. A 60-page annual report produces roughly 1,200.

The element types that matter:

  • Title and Header — section boundaries, useful for section-aware chunking
  • NarrativeText — the prose you actually want to embed
  • Table — with text_as_html so you can keep the grid structure
  • ListItem — often junk, often listicles you need
  • FigureCaption, Footer, PageNumber — usually noise to filter out

How do you install and run it locally?

  1. Python 3.9 or newer. pip install "unstructured[all-docs]" pulls the PDF, image, and Office handlers.
  2. System dependencies matter. On Debian/Ubuntu you need poppler-utils, tesseract-ocr, libreoffice, and pandoc. Missing poppler is the number one install failure.
  3. Partition a file:
from unstructured.partition.auto import partition

els = partition(filename="report.pdf", strategy="hi_res")
for e in els:
    print(e.category, e.metadata.page_number, e.text[:80])
  1. Filter and serialize:
from unstructured.staging.base import elements_to_json
keep = [e for e in els if e.category not in ("Footer", "PageNumber")]
open("out.json", "w").write(elements_to_json(keep))

Which strategy should you pick: fast, hi_res, or ocr_only?

This one setting changes both quality and runtime by an order of magnitude.

Strategy Runtime per 50 pages Best for
fast 2–5 seconds Digital PDFs with a text layer
hi_res 2–6 minutes Layout-heavy docs, tables, multi-column
ocr_only 1–3 minutes Pure scans with no text layer
auto varies Leave it on until you know your corpus

The honest guidance: start with fast. If tables come out garbled or columns interleave, move up to hi_res. hi_res runs a layout detection model on every page and downloads model weights the first time — that first run can take several minutes on a cold machine.

How do you chunk without destroying context?

The default chunk_by_title strategy groups elements under their nearest title, which is usually right for reports and manuals. Max characters default to 500 with a 200-character overlap.

Two tweaks do most of the work. Raise max_characters to 1,000–1,200 for dense technical documents, because 500 characters cuts mid-argument. And call prepend metadata (page number, section title) into each chunk’s text so retrieval can cite something.

For tables, never chunk them. Keep text_as_html as its own chunk and store the HTML alongside the embedding.

Is the hosted API worth it over local?

The hosted Unstructured API charges by page. Free tier covers a few hundred pages a month. Paid pricing starts around $1 per 1,000 pages for the cheaper models and climbs for the higher-accuracy pipelines.

Local is free but not cheap in other ways. hi_res on CPU takes about 1–2 seconds per page. A 10,000-page corpus is a weekend job unless you add a GPU.

Pick the API when your volume is spiky or small. Pick local when your documents are sensitive — legal, medical, HR — and cannot leave your infrastructure.

Where does Unstructured struggle?

Multi-column academic PDFs still interleave columns occasionally, even at hi_res. Check a sample of 20 pages from each new document source before trusting the pipeline.

Handwriting recognition is weak. Signature blocks and handwritten annotations come out as noise or vanish.

And the dependency chain is fragile. LibreOffice is needed for DOCX handling and is a large install; Docker images for it run 3–5 GB. If you are shipping a small service, that matters.

Good fit: RAG pipelines over contracts, financial filings, manuals, and scanned archives. Anyone whose retrieval quality is capped by bad PDF parsing.

Poor fit: casual users who just want text out of one PDF (a browser tool is enough), and teams that cannot run Linux dependencies.

Quick Summary

  • Unstructured returns typed JSON elements, not flat text — that structure powers better chunking.
  • Use fast first; escalate to hi_res only when tables or columns break.
  • Requires poppler, tesseract, libreoffice, and pandoc for full format support.
  • Keep tables as text_as_html chunks; never split them.
  • Hosted API starts near $1 per 1,000 pages; local hi_res costs 1–2 seconds per page on CPU.