How to Install olmocr: Complete Setup Guide for Local and Remote Inference

You can install olmocr using pip with four different flavors: lightweight remote inference (pip install olmocr), local GPU support (pip install "olmocr[gpu]"), Beaker cluster integration (pip install "olmocr[beaker]"), or benchmark dependencies (pip install "olmocr[bench]"), each configured in pyproject.toml to match your hardware and use case.

olmocr is an open-source Python OCR toolkit developed by the Allen Institute for AI that converts PDFs, PNGs, and JPEGs into clean Markdown using vision-language models. Whether you need a lightweight client to connect to remote inference servers or a full GPU-accelerated pipeline running locally, the installation process in allenai/olmocr supports multiple configurations via optional dependencies defined in the repository's pyproject.toml.

System Prerequisites

Before installing olmocr, you must install system-level dependencies for PDF processing and font rendering. These requirements support the image conversion utilities in olmocr/image_utils.py and the text rendering pipeline.

On Ubuntu/Debian systems, install Poppler and Microsoft fonts:

sudo apt-get update
sudo apt-get install poppler-utils \
    ttf-mscorefonts-installer msttcorefonts \
    fonts-crosextra-caladea fonts-crosextra-carlito \
    gsfonts lcdf-typetools

Create a fresh Conda environment to avoid dependency conflicts with other packages:

conda create -n olmocr python=3.11
conda activate olmocr

Installation Methods

The allenai/olmocr repository organizes dependencies into optional extras defined in pyproject.toml. Choose the flavor that matches your infrastructure and whether you plan to run the vision-language model locally or remotely.

Remote Inference (Lightweight)

Install only the core library if you plan to use an external vLLM server via the --server flag. This excludes PyTorch and model files, making it suitable for low-spec machines or distributed clients.

pip install olmocr

This installs the CLI entry point (olmocr) implemented in olmocr/pipeline.py and the work queue system in olmocr/work_queue.py, but delegates inference to remote endpoints.

Local GPU Inference

For local execution on NVIDIA GPUs (≥ 12 GB VRAM), install the GPU flavor which includes PyTorch, Transformers, and vLLM dependencies matched to CUDA 12.8.

pip install "olmocr[gpu]" --extra-index-url https://download.pytorch.org/whl/cu128

Optionally install FlashInfer for faster CUDA inference:

pip install https://download.pytorch.org/whl/cu128/flashinfer/flashinfer_python-0.2.5%2Bcu128torch2.7-cp38-abi3-linux_x86_64.whl

This configuration enables the full pipeline including the filtering logic in olmocr/filter/filter.py and prompt generation in olmocr/prompts/prompts.py to run entirely on your local machine.

Beaker Execution

For large-scale batch jobs on AI2's internal Beaker infrastructure, install the Beaker dependencies:

pip install "olmocr[beaker]"

This adds beaker-py and CLI flags for submitting distributed jobs using the Beaker cluster integration.

Benchmark Suite

To run the comprehensive olmOCR-Bench suite locally (including 7,000+ test cases), install the benchmark dependencies:

pip install "olmocr[bench]"

This pulls in additional packages like tinyhost, playwright, and openai required by the test suite in olmocr/bench/.

Combining Flavors

You can combine multiple extras for complex workflows. For example, to enable both local GPU inference and benchmarking:

pip install "olmocr[gpu,bench]" --extra-index-url https://download.pytorch.org/whl/cu128

Verification

Verify your installation by checking the CLI help output, which reflects the argument parsing logic in olmocr/pipeline.py:

olmocr --help

This should display the full usage instructions for the cli_main function, including options for --markdown, --pdfs, and --server.

Docker Installation

For a containerized deployment that includes the complete model (≈ 30 GB) and all system dependencies, use the official Docker image:

docker pull alleninstituteforai/olmocr:latest-with-model

docker run --gpus all \
  -v $(pwd):/workspace \
  alleninstituteforai/olmocr:latest-with-model \
  -c "olmocr /workspace/output --markdown --pdfs /workspace/sample.pdf"

This approach bundles Poppler, fonts, and the VLLM weights, eliminating the need for local dependency management.

Summary

• Install olmocr via pip with optional extras to match your infrastructure: pip install olmocr for remote inference, pip install "olmocr[gpu]" for local CUDA execution, or pip install "olmocr[beaker]" for cluster jobs.
• System prerequisites include Poppler and Microsoft fonts to support PDF rendering in olmocr/image_utils.py.
• Verification requires running olmocr --help to confirm the CLI entry point from olmocr/pipeline.py is accessible.
• Docker provides a self-contained alternative with the full model weights pre-loaded.

Frequently Asked Questions

What Python version does olmocr require?

olmocr requires Python 3.11 for optimal compatibility with its dependencies, particularly the vLLM and PyTorch stack used in olmocr/pipeline.py. Create a dedicated Conda environment with conda create -n olmocr python=3.11 to avoid conflicts with other packages.

Can I install olmocr without a GPU?

Yes. Install the lightweight remote inference flavor with pip install olmocr, which excludes PyTorch and CUDA dependencies. This configuration relies on the --server flag to send images to an external vLLM endpoint, making it suitable for CPU-only machines or low-resource environments.

Where are the optional dependencies defined in the source code?

All installation flavors and their specific package requirements are declared in the [project.optional-dependencies] table of pyproject.toml in the repository root. The [gpu], [beaker], and [bench] extras map to different subsets of the full dependency graph used by components like olmocr/work_queue.py and olmocr/viewer/dolmaviewer.py.

How do I run olmocr after installation?

After installation, use the olmocr CLI command to process PDFs. For local GPU inference: olmocr ./workspace --markdown --pdfs document.pdf. For remote inference, add --server http://host:8000/v1 --model allenai/olmOCR-2-7B-1025-FP8. The CLI entry point is defined in pyproject.toml and implemented by the cli_main function in olmocr/pipeline.py.

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