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

> Install olmOCR easily with pip for fast remote or local GPU inference. Follow our guide for Python 3.11 and Poppler setup.

- Repository: [Ai2/olmocr](https://github.com/allenai/olmocr)
- Tags: getting-started
- Published: 2026-07-07

---

**Install olmOCR via `pip install olmocr` for lightweight remote inference, or `pip install "olmocr[gpu]"` for local GPU execution, ensuring you have Python 3.11 and Poppler system dependencies installed first.**

The allenai/olmocr repository provides a Python-based OCR toolkit that converts PDFs and images into clean Markdown using vision-language models. Whether you need a lightweight client for remote inference or a full GPU-accelerated pipeline, understanding how to install olmocr correctly ensures optimal performance. This guide covers all installation flavors defined in [`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml), from minimal setups to complete local deployments.

## Prerequisites and System Dependencies

Before installing the Python package, you must install system-level dependencies for PDF processing. The [`olmocr/image_utils.py`](https://github.com/allenai/olmocr/blob/main/olmocr/image_utils.py) module relies on Poppler for rendering PDF pages to images, while the filtering components in [`olmocr/filter/filter.py`](https://github.com/allenai/olmocr/blob/main/olmocr/filter/filter.py) expect specific font libraries for document analysis.

### Install Poppler and Fonts (Ubuntu/Debian)

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

```

## Set Up Your Python Environment

Create an isolated Conda environment to avoid dependency conflicts, as the package pins specific versions of PyTorch and transformers.

```bash
conda create -n olmocr python=3.11
conda activate olmocr

```

## Installation Methods

The [`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml) file defines four optional dependency groups in `[project.optional-dependencies]` tailored to different use cases. Choose the flavor that matches your hardware and workflow.

### Remote Inference (Lightweight)

Install only the core library without PyTorch or CUDA dependencies. This connects to external vLLM servers via the `--server` flag implemented in [`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py).

```bash
pip install olmocr

```

### Local GPU Installation

Install the full stack including `torch`, `transformers`, and `vllm` for local inference. This requires an NVIDIA GPU with at least 12GB VRAM.

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

```

Optionally add FlashInfer for faster CUDA inference:

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

```

### Beaker Cluster Setup

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

```bash
pip install "olmocr[beaker]"

```

This enables the CLI flags for submitting jobs to Beaker clusters, utilizing the distributed work queue implementation in [`olmocr/work_queue.py`](https://github.com/allenai/olmocr/blob/main/olmocr/work_queue.py).

### Benchmark Suite Installation

To run the comprehensive olmOCR-Bench validation suite (7k+ test cases), install the benchmark dependencies:

```bash
pip install "olmocr[bench]"

```

You can combine flavors. For example, to install both GPU and benchmark dependencies:

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

```

## Verify the Installation

Confirm the CLI entry point is accessible. The `olmocr` command is defined in [`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml) under `[project.scripts]` and implemented in [`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py) via the `cli_main` function.

```bash
olmocr --help

```

This should display the full CLI usage documentation, including options for `--markdown`, `--pdfs`, and `--server`.

## Usage Examples

Once installed, you can process documents using the command-line interface that coordinates [`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py) with [`olmocr/work_queue.py`](https://github.com/allenai/olmocr/blob/main/olmocr/work_queue.py) for task distribution.

### Process a Single PDF Locally

```bash

# Download a sample PDF

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

# Run OCR pipeline

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

```

Results appear in [`./workspace/markdown/sample.md`](https://github.com/allenai/olmocr/blob/main/./workspace/markdown/sample.md), including LaTeX math and formatted tables generated by the prompt logic in [`olmocr/prompts/prompts.py`](https://github.com/allenai/olmocr/blob/main/olmocr/prompts/prompts.py).

### Connect to a Remote vLLM Server

For setups without local GPU resources, use the remote inference mode:

```bash
olmocr ./workspace \
    --server http://my-vllm:8000/v1 \
    --model allenai/olmOCR-2-7B-1025-FP8 \
    --markdown \
    --pdfs tests/gnarly_pdfs/*.pdf

```

The pipeline forwards each page to the specified server endpoint, avoiding local GPU load while using [`olmocr/image_utils.py`](https://github.com/allenai/olmocr/blob/main/olmocr/image_utils.py) for preprocessing.

### Run with Docker

For containerized deployments, use the official image which bundles the 30GB model and all system dependencies:

```bash
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"

```

## Summary

- **Install system dependencies first**: Poppler and fonts are required for PDF rendering in [`olmocr/image_utils.py`](https://github.com/allenai/olmocr/blob/main/olmocr/image_utils.py).
- **Choose your flavor**: Use `pip install olmocr` for remote inference, or `pip install "olmocr[gpu]"` with CUDA extras for local GPU execution.
- **Verify with CLI**: Run `olmocr --help` to confirm the installation correctly linked the entry point defined in [`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml).
- **Consider Docker**: The `alleninstituteforai/olmocr:latest-with-model` image provides a complete environment without local dependency management.

## Frequently Asked Questions

### What Python version does olmOCR require?

olmOCR requires Python 3.11. Create a dedicated Conda environment with `conda create -n olmocr python=3.11` to avoid conflicts with other packages, as the dependency chain includes specific versions of PyTorch and transformers that may clash with existing installations.

### Do I need a GPU to run olmOCR?

No. You can run olmOCR on CPU-only machines using the remote inference mode (`pip install olmocr`) which connects to external vLLM servers via the `--server` flag. However, for local GPU inference, you need an NVIDIA GPU with at least 12GB VRAM and must install the GPU flavor with `pip install "olmocr[gpu]"`.

### How do I install olmOCR without CUDA dependencies?

Install the lightweight version with `pip install olmocr`. This excludes PyTorch, CUDA toolkit, and vLLM from the installation, making it suitable for low-spec machines or client-only setups that use the `--server` flag to connect to remote inference endpoints defined in [`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py).

### Where is the CLI entry point defined in the source code?

The CLI entry point is defined in [`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml) under the `[project.scripts]` section, pointing to `olmocr.pipeline:cli_main`. The actual argument parsing and orchestration logic resides in [`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py), which coordinates with [`olmocr/work_queue.py`](https://github.com/allenai/olmocr/blob/main/olmocr/work_queue.py) for distributed processing and [`olmocr/image_utils.py`](https://github.com/allenai/olmocr/blob/main/olmocr/image_utils.py) for PDF rendering.