olmocr
CLI Toolallenai/olmocr
Toolkit for linearizing PDFs into clean text for LLM datasets.
Overview
A toolkit that converts PDFs and images into clean Markdown text with natural reading order. Supports complex formatting, tables, equations, and handwriting. Designed for preparing high-quality training data for large language models.
README Preview
\n \n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n\nA toolkit for converting PDFs and other image-based document formats into clean, readable, plain text format.\n\nTry the online demo: [https://olmocr.allenai.org/](https://olmocr.allenai.org/)\n\nFeatures:\n - Convert PDF, PNG, and JPEG based documents into clean Markdown\n - Support for equations, tables, handwriting, and complex formatting\n - Automatically removes headers and footers\n - Convert into text with a natural reading order, even in the presence of\n figures, multi-column layouts, and insets\n - Efficient, less than $200 USD per million pages converted\n - (Based on a 7B parameter VLM, so it requires a GPU)\n\n### News\n - October 21, 2025 - v0.4.0 - [New model release](https://huggingface.co/allenai/olmOCR-2-7B-1025-FP8), boosts olmOCR-bench score by ~4 points using synthetic data and introduces RL training.\n - August 13, 2025 - v0.3.0 - [New model release](https://huggingface.co/allenai/olmOCR-7B-0825-FP8), fixes auto-rotation detection, and hallucinations on blank documents.\n - July 24, 2025 - v0.2.1 - [New model release](https://huggingface.co/allenai/olmOCR-7B-0725-FP8), scores 3 points higher on [olmOCR-Bench](https://github.com/allenai/olmocr/tree/main/olmocr/bench), also runs significantly faster because it's default FP8, and needs much fewer retries per document.\n - July 23, 2025 - v0.2.0 - New cleaned up [trainer code](https://github.com/allenai/olmocr/tree/main/olmocr/train), makes it much simpler to train olmOCR models yourself.\n - June 17, 2025 - v0.1.75 - Switch from sglang to vllm based inference pipeline, updated docker image to CUDA 12.8.\n - May 23, 2025 - v0.1.70 - Official docker support and images are now available! [See Docker usage](#using-docker)\n - May 19, 2025 - v0.1.68 - [olmOCR-Bench](https://github.com/allenai/olmocr/tree/main/olmocr/bench) launch, scoring 77.4. Launch includes 2 point performance boost in olmOCR pipeli
FAQ (3)
TroubleshootingWhy does olmOCR 0.4.4 hang indefinitely after OCR completes and never exit?
This is a regression in olmOCR 0.4.4 caused by missing semaphore cleanup; it commonly occurs when using an external vLLM/server-based provider. Upgrade to the fixed release:
pip install --upgrade olmocr==0.4.5Verify the CLI returns after processing and that all workers terminate. If you cannot upgrade immediately, downgrade to the last working release:
pip install olmocr==0.4.3Avoid olmOCR 0.4.4 for scripted or automated workflows because the parent process can remain alive until manually terminated with SIGTERM/SIGKILL.
TroubleshootingHow do I keep olmOCR's --markdown output inside the workspace when --pdfs is an absolute path?
Older olmOCR versions used the absolute PDF path directly when deriving the Markdown output path, so joining it with the workspace resolved to the PDF's original directory. This is fixed by PR #400. Upgrade to a release containing the fix or the latest main branch:
pip install -U git+https://github.com/allenai/olmocr.gitThen rerun:
python -m olmocr.pipeline ./localworkspace --markdown \
--pdfs /my/path/to/my/personal/pdf.pdf \
--model allenai/olmOCR-2-7B-1025-FP8The output is now kept under the workspace, with the absolute path preserved to avoid filename collisions:
./localworkspace/markdown/absolute/my/path/to/my/personal/pdf.mdWorkaround on older versions: run the command from the PDF's directory and pass only the filename:
cd /my/path/to/my/personal
python -m olmocr.pipeline /path/to/localworkspace --markdown \
--pdfs pdf.pdf \
--model allenai/olmOCR-2-7B-1025-FP8This produces localworkspace/markdown/pdf.md.
TroubleshootingHow do I fix olmOCR FP8 running at about 0.5 tokens/s and spilling into shared memory on a 12 GB Blackwell GPU?
The slowdown occurs because the Transformers inference path upcasts FP8 weights to FP16, raising memory use from about 7 GB to roughly 20 GB. Use the vLLM backend instead; olmOCR uses vLLM by default, and vLLM can run native FP8 when the installed GPU stack supports it. Use WSL2/Linux with a CUDA 12.8, Blackwell sm_120-compatible PyTorch build, then install or upgrade to a vLLM build that supports Blackwell FP8. Verify the setup with python -c "import torch; print(torch.cuda.get_device_capability())" (Blackwell should report a 12.x capability) and python -c "import vllm; print(vllm.__version__)". Make sure the model is actually loaded through vLLM; a Transformers load will still upcast to FP16. The separate hard-coded 15 GB check in olmocr/check.py can be temporarily lowered or removed only after native FP8 vLLM inference is confirmed. Changing that check without native FP8 support will not prevent the FP16 upcast or shared-memory spill.