# What Are the Dependencies for olmOCR? A Complete Guide to Core and Optional Packages

> Discover the core and optional dependencies for olmOCR. Learn which Python packages you need for PDF processing, GPU inference, and distributed training with this comprehensive guide.

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

---

**olmOCR splits its Python dependencies into a lightweight core stack for PDF processing and optional extras for GPU inference, benchmarking, and distributed training.**

The allenai/olmocr repository declares all runtime requirements in [`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml), distinguishing between the 16 essential packages needed for every installation and feature-specific groups that you install only when required.

## Core Dependencies

The essential dependencies are listed under the `dependencies` key in [`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml) ([lines 23–39](https://github.com/allenai/olmocr/blob/main/pyproject.toml#L23)). These packages enable the end-to-end OCR pipeline without requiring GPU acceleration or deep learning frameworks.

### PDF and Image Processing

- **pypdf>=5.2.0**: Handles PDF parsing, page counting, and metadata extraction.
- **pypdfium2**: Fast PDF rendering to images, used by the `render_pdf_to_base64png` utility.
- **Pillow**: Image manipulation including rotation and format conversion.

### Cloud and Storage

- **smart_open**: Transparent reading of files from local filesystems, S3, and GCS.
- **boto3**: AWS SDK for S3 work-queue handling and PDF storage.
- **cached-path**: Cached filesystem path handling for downloaded resources.
- **filelock**: Simple file-based locking used by cache directories to ensure safe concurrent access.

### HTTP and Networking

- **httpx**: Async HTTP client used for OpenAI-compatible server calls.
- **requests**: Traditional HTTP client for simple fallback HTTP calls.
- **cryptography**: Secure handling of credentials for S3 and Beaker secrets.

### Text Processing and Output

- **ftfy**: Fixes Unicode text anomalies after OCR.
- **bleach**: Sanitizes HTML and Markdown output.
- **markdown2**: Converts Markdown to HTML for viewer utilities.
- **markdownify**: Extracts clean Markdown from HTML fragments.
- **lingua-language-detector**: Automatic language detection for filtering PDFs by content language.

### Performance and Serialization

- **orjson**: High-performance JSON serialization for Dolma documents.
- **zstandard**: Fast compression and decompression of intermediate files.

## Optional Dependency Groups

olmOCR uses the `[project.optional-dependencies]` section in [`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml) to declare feature-specific extras. Install these using bracket notation (e.g., `pip install "olmocr[gpu]"`).

### GPU Support

The **`gpu`** extra adds the heavy-weight inference backend for local model execution:

- `torch>=2.7.0`
- `transformers==4.57.3`
- `vllm==0.11.2`

Install with:

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

```

These packages power the VLLM server and model loading in [`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py). Without this group, olmOCR operates in remote-only mode, delegating inference to external APIs.

### Beaker Integration

The **`beaker`** extra includes `beaker-py` for submitting jobs to the Beaker cluster platform. This is essential for distributed processing workflows on the AllenAI infrastructure.

### Development Tools

The **`dev`** extra provides linting and testing utilities including `ruff`, `mypy`, `black`, `isort`, and `pytest`.

### Benchmark Suite

The **`bench`** extra installs packages required for the built-in evaluation framework in `olmocr/bench/`:

`tinyhost`, `fuzzysearch`, `rapidfuzz`, `sequence_align`, `syntok`, `openai`, `google-genai`, `anthropic`, `playwright`, `lxml`, `flask`, `wordfreq`

### Training Pipeline

The **`train`** extra enables fine-tuning and reinforcement learning scripts in `olmocr/train/`:

`torch`, `torchvision`, `accelerate`, `trl`, `peft`, `wandb`, `omegaconf`, `einops`, `augraphy`

### ELO Evaluation

The **`elo`** extra provides `numpy`, `scipy`, `pandas`, and `matplotlib` for simple evaluation and visualization utilities.

## Installation Examples

Install the minimal package for remote API usage:

```bash
pip install olmocr

```

Install with local GPU inference support:

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

```

Install the complete development and benchmarking suite:

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

```

## How Dependencies Map to Source Code

The dependency structure directly reflects the architecture of the olmOCR pipeline:

- **[`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py)**: Wires together PDF rendering (via `pypdfium2`), VLLM calls (via `httpx` or `torch`/`vllm`), and Dolma document generation (using `orjson`).
- **[`olmocr/s3_utils.py`](https://github.com/allenai/olmocr/blob/main/olmocr/s3_utils.py)**: Uses `boto3` and `smart_open` for downloading PDFs and managing work-queue files from S3.
- **[`olmocr/filter/filter.py`](https://github.com/allenai/olmocr/blob/main/olmocr/filter/filter.py)**: Imports `lingua-language-detector` for language-based filtering and spam detection.
- **[`olmocr/image_utils.py`](https://github.com/allenai/olmocr/blob/main/olmocr/image_utils.py)**: Relies on `Pillow` for image conversion, rotation, and format detection.

The modular dependency design ensures that lightweight deployments only pull essential packages, while full-scale training and inference environments can install the complete toolchain.

## Summary

- **Core dependencies** in [`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml) include 16 essential packages for PDF processing (`pypdf`, `pypdfium2`), cloud storage (`boto3`, `smart_open`), HTTP communication (`httpx`, `requests`), and text sanitization (`ftfy`, `bleach`).
- **Optional extras** provide six feature groups: `gpu` for local inference, `beaker` for cluster computing, `dev` for development tools, `bench` for evaluation, `train` for fine-tuning, and `elo` for visualization.
- The minimal install (`pip install olmocr`) supports remote API workflows, while `pip install "olmocr[gpu]"` enables local VLLM inference.
- All dependencies are managed through standard Python packaging in [`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml) with no external system requirements beyond the optional CUDA toolchain for GPU support.

## Frequently Asked Questions

### What's the difference between `pip install olmocr` and `pip install "olmocr[gpu]"`?

The base installation includes only the 16 core dependencies needed for PDF processing and remote API communication. The `gpu` extra adds `torch`, `transformers`, and `vllm`, which are required to run the VLLM inference server locally. Without the GPU extra, olmOCR can only process PDFs by sending images to external OpenAI-compatible APIs.

### Why does olmOCR require both `pypdf` and `pypdfium2`?

`pypdf>=5.2.0` handles metadata extraction, page counting, and text parsing, while `pypdfium2` provides fast rasterization of PDF pages to images. The pipeline uses `pypdf` for document analysis and `pypdfium2` for rendering pages to base64-encoded PNGs that get sent to the vision-language model.

### Can I use olmOCR without installing PyTorch?

Yes. The core dependencies do not include `torch` or related deep learning libraries. You can process PDFs using remote inference by specifying an API endpoint with the `--server` flag, which only requires `httpx` (already included in the base install). PyTorch is only needed when using the `gpu` extra for local model execution.

### What are the Beaker dependencies used for?

The `beaker` extra installs `beaker-py`, which provides client libraries for AllenAI's Beaker cluster platform. This allows olmOCR to submit distributed processing jobs to cloud infrastructure, manage experiments, and handle large-scale PDF processing workflows that exceed local compute resources.