Using pdf-inspector for the first time, most people worry about "will it even install and parse?" In practice, what shapes your experience is getting three things straight: what type of PDF you're holding, where it runs best, and what might be lost in the output. Sort those out and your first parse takes under five minutes.

Set the right expectations

pdf-inspector is a parsing library, not a PDF viewer. Its job: figure out whether a PDF can be read directly, then turn it into clean, position-aware Markdown when it can. Accept three things up front:

• Parsing happens locally — no network, no uploads; a text-based PDF finishes end-to-end within 200ms
• The output is plain-text Markdown — visual styling (colors, decorative graphics) isn't preserved
• Purely scanned/image-based pages yield no text — instead of pretending success, it tells you exactly which pages need OCR

Know before you start

• Core abilities: classification (TextBased / Scanned / ImageBased / Mixed) + extraction (position-aware + Markdown)
• License: MIT — free, commercial use allowed
• Bindings: Rust / Node.js / Python / browser (WebAssembly) / CLI
• Known limits: the web WASM build includes no OCR; scanned pages need an OCR runtime
• Repository: github.com/firecrawl/pdf-inspector

Your first parse: CLI three-liner

The CLI is the fastest on-ramp — no project setup needed. As a Rust user, install once with cargo install pdf-inspector and you get two tools:

# 1. Classify first: can this PDF be read directly?
detect-pdf annual-report.pdf --analyze --json

# 2. Convert to Markdown, print to terminal
pdf2md annual-report.pdf

# 3. Only some pages, written to a file
pdf2md annual-report.pdf --pages 1-3 -o report.md

Classify before you extract

detect-pdf spends only ~10–50ms telling you the document type and which pages need OCR. Seeing TextBased before running pdf2md is the officially recommended routing move.

Open the output and eyeball it: did headings become # levels? Are multi-column sections in the right order? Do tables look regular? That's pdf-inspector showing its work.

Common flags at a glance

Usage	Meaning
pdf2md <file>	Parse; Markdown goes to stdout
pdf2md <file> -o out.md	Write to a file
pdf2md <file> --pages 1-3	Process selected pages only
pdf2md <file> --compact	Token-saving compact output
pdf2md <file> --json	Structured JSON output
detect-pdf <file> --analyze --json	Classification + analysis info

First lines in every language

Beyond the CLI, every binding starts in a few lines:

// Node.js
import { classifyPdf } from '@firecrawl/pdf-inspector'
const result = classifyPdf(pdfBuffer)
console.log(result.pdfType)   // "TextBased"

# Python
import pdf_inspector
result = pdf_inspector.process_pdf("document.pdf")
print(result.pdf_type)        # "text_based"
print(result.markdown)

// Rust
use pdf_inspector::process_pdf;
let result = process_pdf("document.pdf")?;
println!("{}", result.markdown.unwrap_or_default());

// Browser (WASM)
import init, { processPdf } from '@firecrawl/pdf-inspector-wasm'
await init()
const { pdfType, markdown } = processPdf(pdfBytes)

Want to go deeper on one? See the API quick reference or jump straight to your language's page (Node.js / Python / Rust / WebAssembly / CLI).

Three common misconceptions

"Every PDF can be converted directly"

No. About 54% of PDFs are native text and convert directly; the rest are scans or images that require OCR. pdf-inspector's whole value is spending tens of milliseconds to tell you which one you're holding — stop sending text-based files to expensive OCR.

"It will restore the layout losslessly"

It won't, and shouldn't. The goal is complete information in correct structure (heading levels, reading order, tables intact), not pixel-perfect fidelity. For pixels use a PDF viewer; for clean LLM input use pdf-inspector.

"The output is garbled, so the library must be broken"

More likely the source file's font encoding was already broken (GID-encoded fonts, missing ToUnicode CMaps). pdf-inspector flags those pages (see has_encoding_issues in Python, needsOcr in region extraction). Route them to OCR instead of retrying.

Newcomer checklist

• Install via cargo install pdf-inspector, run detect-pdf to see the type
• On Node servers, use the async variants (processPdfAsync, etc.) so the event loop stays free
• Pass pages when you only need part of a document — saves time and memory
• Feed LLMs with --compact / profile: "compact" to save tokens
• A "needs OCR" verdict isn't a bug — it's saving you money

One sentence to remember: pdf-inspector is the entry point of the "PDF → structured Markdown" pipeline — classify first, then decide how to extract. Next, see the API quick reference or jump to your language.