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

> Easily convert a single PDF to Markdown with olmOCR. Use the CLI or Python code to process PDFs into structured Markdown files quickly and efficiently.

- Repository: [Ai2/olmocr](https://github.com/allenai/olmocr)
- Tags: how-to-guide
- Published: 2026-07-02

---

**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`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/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.

```bash

# 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`](https://github.com/allenai/olmocr/blob/main/./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:

```bash
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`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py)** – Core orchestrator that builds work-items, manages VLLM inference queues, and coordinates Markdown output generation.
- **[`olmocr/data/renderpdf.py`](https://github.com/allenai/olmocr/blob/main/olmocr/data/renderpdf.py)** – Contains `render_pdf_to_base64png` for PDF-to-image conversion using Poppler.
- **[`olmocr/viewer/dolmaviewer.py`](https://github.com/allenai/olmocr/blob/main/olmocr/viewer/dolmaviewer.py)** – Utility for visualizing intermediate Dolma JSONL files during development and debugging.
- **[`olmocr/bench/tests.py`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py) benefits significantly from CUDA acceleration.