Skip to content
Get packs

Guide · Open source

How to use pdf-inspector: install, convert PDFs to Markdown and detect scans

Updated · written with AI from the project's own documentation and checked against our catalogue data

pdf-inspector is an open-source Rust library, with Python, Node.js and browser WebAssembly bindings, that checks whether a PDF is text-based or scanned and then extracts its text as clean Markdown. It is aimed at developers and teams who process many PDFs and want to send only the scanned ones to OCR. After this guide you will be able to install it, run detection and conversion from code or the command line, and understand when OCR is needed.

pdf-inspectorfirecrawl/pdf-inspector · ★ 19.8k · MIT

Quick start

  1. 1Pick your interface. Choose Python, Node.js, browser WebAssembly or the Rust CLI based on where your PDFs are processed.
  2. 2Install the package. Run the matching install command: pip install pdf-inspector, npm install @firecrawl/pdf-inspector, or cargo install pdf-inspector.
  3. 3Run detection. Process a file and check pdf_type or run detect-pdf to see whether it is TextBased, Scanned, ImageBased or Mixed.
  4. 4Convert text-based PDFs. Read the markdown field, or run pdf2md with flags such as --pages or --select-pages to control the output.
  5. 5Route scanned pages to OCR (optional). If you need OCR, build with the ocr feature, install PDFium and ONNX Runtime, and set their library paths before running --ocr auto.

What pdf-inspector does

The tool first decides whether each PDF is TextBased, Scanned, ImageBased or Mixed. It does this by sampling content streams, and it returns a confidence score from 0.0 to 1.0 and per-page OCR routing. Text-based PDFs are converted to Markdown without OCR.

Text extraction keeps position information, font details and multi-column reading order. Markdown output can include headings, lists, code blocks, tables, bold and italic text, links and page breaks.

  • Detects TextBased, Scanned, ImageBased or Mixed PDFs
  • Extracts text with font info and X/Y coordinates
  • Converts to Markdown: headings, lists, tables, code blocks and links
  • Optional selective OCR, only for pages that need it

Install pdf-inspector for Python, Node.js or Rust

Choose the package for your language. Each install command below comes from the project README. The Rust route needs a Rust toolchain, Python needs Python, and the Node.js route needs Node.js.

  • Python: pip install pdf-inspector
  • Node.js: npm install @firecrawl/pdf-inspector
  • Rust CLI: cargo install pdf-inspector
pip install pdf-inspector

Convert a PDF to Markdown in Python

Import the package and call process_pdf with the file path. The result exposes the detected type and the Markdown string, which is None when no Markdown is produced.

The README notes that clean text PDFs do not load the external OCR runtime, so this basic call works without OCR setup.

import pdf_inspector result = pdf_inspector.process_pdf("document.pdf") print(result.pdf_type) # "text_based", "scanned", "image_based", "mixed" print(result.markdown) # Markdown string or None

Use the command-line tools (pdf2md and detect-pdf)

After cargo install pdf-inspector, two commands are available. pdf2md converts a PDF to Markdown, and detect-pdf only reports the classification. Flags let you change the output.

  • pdf2md document.pdf converts to Markdown
  • pdf2md document.pdf --json adds document information such as title, author and dates
  • pdf2md document.pdf --raw outputs Markdown without headers
  • pdf2md document.pdf --compact collapses long dot leaders and similar padding
  • pdf2md document.pdf --pages inserts <!-- Page N --> markers
  • pdf2md document.pdf --select-pages 1,3,5-10 processes only chosen pages
  • detect-pdf document.pdf --json reports detection only
pdf2md document.pdf pdf2md document.pdf --select-pages 1,3,5-10 detect-pdf document.pdf --json

Add OCR for scanned pages (optional)

OCR is not part of the default Rust and browser builds. Rust and CLI users opt in at build time with the ocr feature. OCR also needs PDFium and ONNX Runtime installed separately, and their paths are set through environment variables. The README points to an OCR runtime setup guide for pinned downloads and platform support.

Native Python and Node packages include the OCR integration, but the PDFium, ONNX Runtime and model files still have to be present, and they are only used when a page is routed to OCR.

  • Build with: cargo install pdf-inspector --features ocr --bin pdf2md
  • Set PDFIUM_LIB_PATH and ORT_DYLIB_PATH to your library locations
cargo install pdf-inspector --features ocr --bin pdf2md PDFIUM_LIB_PATH=/path/to/libpdfium ORT_DYLIB_PATH=/path/to/libonnxruntime \ pdf2md scan.pdf --ocr auto --json

Use it in the browser with WebAssembly

The browser build runs the same Rust parser locally in browsers and Web Workers, with embedded CMaps and no server round trip. Install the wasm package, initialise it, then pass the file bytes to processPdf.

npm install @firecrawl/pdf-inspector-wasm

What people use it for

  • Routing a batch of mixed PDFs so text-based files are converted locally and scanned ones go to OCR
  • Converting reports, research papers, invoices or legal PDFs into Markdown on your own machine
  • Extracting text from PDFs in a browser app without sending the file to a server
  • Running detect-pdf in a pipeline to log which documents need OCR

Frequently asked questions

How do I install pdf-inspector?

Use the package manager for your language: pip install pdf-inspector for Python, npm install @firecrawl/pdf-inspector for Node.js, or cargo install pdf-inspector for the Rust CLI. The Rust route requires a Rust toolchain, Python needs Python, and Node.js needs Node.js.

Is pdf-inspector free and what is its licence?

pdf-inspector is released under the MIT licence, as stated in the project README. The licence badge and LICENSE file in the repository describe the terms.

Does pdf-inspector need OCR?

No, for text-based PDFs it extracts text and converts to Markdown without OCR. OCR is optional and only applies to pages routed to it, and it requires PDFium and ONNX Runtime to be installed separately.

What is the difference between pdf2md and detect-pdf?

pdf2md converts a PDF to Markdown, while detect-pdf only classifies it as text-based, scanned, image-based or mixed. Use detect-pdf when you only need to decide routing.

Can I use pdf-inspector in the browser?

Yes. The browser WebAssembly build runs locally in browsers and Web Workers, so the file does not need a server round trip. Install @firecrawl/pdf-inspector-wasm to use it.

How does pdf-inspector compare to PyMuPDF4LLM or MarkItDown?

The README benchmark on the opendataloader-bench corpus of 200 PDFs scores pdf-inspector 0.875 overall, ahead of the other local engines it lists, but it is a single corpus evaluation and results on unusual layouts may differ. Test on your own documents before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

pdf-inspector suits developers and teams who process many native-text PDFs and want local, fast Markdown conversion with scanned files routed separately. It is less suitable if you want a one-off conversion without installing a toolchain, or if most of your documents are scans and you need OCR as the main feature.

Install options & downloads