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

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, 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 (lines 23–39). 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 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:

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. 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:

pip install olmocr

Install with local GPU inference support:

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

Install the complete development and benchmarking suite:

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: Wires together PDF rendering (via pypdfium2), VLLM calls (via httpx or torch/vllm), and Dolma document generation (using orjson).
• olmocr/s3_utils.py: Uses boto3 and smart_open for downloading PDFs and managing work-queue files from S3.
• olmocr/filter/filter.py: Imports lingua-language-detector for language-based filtering and spam detection.
• 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 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 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.

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