How to Convert a Single PDF to Markdown Using olmOCR: CLI and Python Guide

You can convert a single PDF to Markdown using olmOCR by running the CLI command olmocr ./workspace --markdown --pdfs input.pdf, which automatically renders pages to images, processes them through a vision-language model, and outputs structured Markdown files.

The allenai/olmocr repository provides an end-to-end open-source pipeline for extracting clean, readable text from PDF documents. By combining Poppler-based PDF rendering with local vision-language inference, the toolkit converts image-based documents and digital PDFs into Markdown that preserves headings, tables, equations, and reading order. This guide covers the complete workflow for processing individual PDF files using both the command-line interface and underlying Python modules.

The Three-Stage Conversion Pipeline

olmOCR processes PDFs through a multi-stage pipeline orchestrated by olmocr/pipeline.py. Understanding these stages helps troubleshoot extraction quality and optimize performance.

Stage 1: PDF Rendering to Base64 PNG Images

First, olmocr/data/renderpdf.py rasterizes each page using the render_pdf_to_base64png function. This utility leverages Poppler utilities (via pdf2image) to convert PDF pages into normalized PNG images, removing headers and footers while standardizing page dimensions for consistent model input.

Stage 2: Vision-Language Model Inference

The pipeline submits base64-encoded images to a VLLM-served instance of allenai/olmOCR-2-7B-1025-FP8. Located in the core pipeline logic, this step generates structured YAML output containing extracted text, table metadata, mathematical expressions, and reading-order annotations.

Stage 3: Markdown Generation and File Output

When you specify the --markdown flag, the system post-processes the structured YAML into plain Markdown. The final files write to <workspace>/markdown/, preserving the original folder hierarchy and including properly formatted headings, math blocks, and footnotes.

Converting a PDF via Command Line

To convert a single PDF to Markdown using olmOCR, first ensure you have a workspace directory created, then invoke the CLI tool.

# Download a sample PDF (optional)

curl -o olmocr-sample.pdf \
   https://olmocr.allenai.org/papers/olmocr_3pg_sample.pdf

# Convert to Markdown using local GPU inference

olmocr ./localworkspace --markdown --pdfs olmocr-sample.pdf

After execution, find the extracted content at ./localworkspace/markdown/olmocr-sample.md. The CLI is a thin wrapper around the Python module and handles workspace creation, intermediate file management, and cleanup automatically.

Programmatic Conversion Using Python

For integration into custom workflows, invoke the pipeline directly via Python module execution:

python -m olmocr.pipeline ./localworkspace \
     --markdown \
     --pdfs olmocr-sample.pdf

This equivalent call provides the same functionality as the olmocr CLI command, allowing you to embed PDF conversion into automated scripts or Jupyter notebooks.

Workspace Structure and Debugging

The workspace directory (e.g., ./localworkspace) serves as the central hub for all processing artifacts. It stores intermediate Dolma JSONL files containing raw model outputs alongside the final Markdown tree. To inspect these intermediate representations during debugging, use olmocr/viewer/dolmaviewer.py, which provides visualization utilities for the JSONL data before final Markdown generation.

Key Source Files in the Repository

The allenai/olmocr implementation relies on these specific components:

• olmocr/pipeline.py – Core orchestrator that builds work-items, manages VLLM inference queues, and coordinates Markdown output generation.
• olmocr/data/renderpdf.py – Contains render_pdf_to_base64png for PDF-to-image conversion using Poppler.
• olmocr/viewer/dolmaviewer.py – Utility for visualizing intermediate Dolma JSONL files during development and debugging.
• olmocr/bench/tests.py – Test suite validating Markdown extraction accuracy, including table parsing and equation reconstruction.

Summary

• One-line conversion: Execute olmocr ./workspace --markdown --pdfs file.pdf to process any PDF into Markdown.
• Three-stage pipeline: Rendering (render_pdf_to_base64png) → Vision-language inference (allenai/olmOCR-2-7B-1025-FP8) → Markdown post-processing.
• Output location: Generated files appear in <workspace>/markdown/ with preserved directory structure.
• Python alternative: Use python -m olmocr.pipeline for programmatic access to the same functionality.

Frequently Asked Questions

What model does olmOCR use for PDF text extraction?

According to the allenai/olmocr source code, the pipeline defaults to allenai/olmOCR-2-7B-1025-FP8, a vision-language model served via VLLM. This model processes the rasterized page images and outputs structured YAML containing the extracted content.

Where are the intermediate processing files stored during conversion?

The workspace directory specified in your command holds intermediate Dolma JSONL files alongside the final Markdown output. You can visualize these intermediate representations using olmocr/viewer/dolmaviewer.py to debug extraction quality before final Markdown generation.

Can I convert multiple PDFs with a single command?

While this guide focuses on single-file conversion, the --pdfs argument accepts multiple paths. The pipeline processes each PDF sequentially, writing individual Markdown files to the workspace while preserving the original folder hierarchy.

Does olmOCR require GPU acceleration?

Yes, the inference stage requires a local GPU to run the allenai/olmOCR-2-7B-1025-FP8 model efficiently. The rendering and Markdown generation stages run on CPU, but the vision-language model inference performed in olmocr/pipeline.py benefits significantly from CUDA acceleration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}