Nougat OCR CLI

A command-line tool for OCR processing using Meta's Nougat model. Extract text from PDFs with GPU acceleration (CUDA and Apple Metal).

Installation

Requires Python 3.11 and a GPU (recommended).

pip install nougat-ocr-cli

Or from source:

git clone https://github.com/r-uben/nougat-ocr-cli.git
cd nougat-ocr-cli
uv sync

Quick start

# Process a single file
nougat-ocr paper.pdf

# Process a directory
nougat-ocr ./papers/ -o ./results/

# Preview what would be processed (no model loading)
nougat-ocr ./papers/ --dry-run

# Process specific pages (zero-indexed)
nougat-ocr paper.pdf --pages 0-5

# Use CPU instead of GPU
nougat-ocr paper.pdf --device cpu

Options

Usage: nougat-ocr [OPTIONS] INPUT_PATH

Options:
  -o, --output-dir PATH           Output directory (default: <input_dir>/nougat_ocr_output/)
  --model TEXT                    Nougat model tag (default: 0.1.0-base)
  --batch-size N                  Batch size for inference (auto-detected if not set)
  --full-precision                Use FP32 instead of BF16 (slower but more accurate)
  --pages TEXT                    Page range (e.g., '0-5' or '1,3,5')
  --device [auto|cuda|mps|cpu]    Device for inference (default: auto)

  --reprocess                     Reprocess already-processed files
  --dry-run                       List files without loading the model
  -q, --quiet                     Suppress all output except errors
  -v, --verbose                   Enable verbose/debug output
  --info                          Show device and system info
  --version                       Show version
  --help                          Show this message

Output structure

nougat_ocr_output/
├── document_name/
│   └── document_name.md        # OCR markdown (clean text only)
├── another_document/
│   └── ...
└── metadata.json               # processing stats, checksums, file list

Device selection

Nougat auto-detects the best available device:

1. CUDA — NVIDIA GPUs (fastest)
2. MPS — Apple Metal on M-series Macs
3. CPU — fallback (slow, not recommended for large documents)

Override with --device cuda|mps|cpu.

Development

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Lint
uv run ruff check .

# Format
uv run ruff format .

# Type check
uv run mypy nougat_ocr/ --ignore-missing-imports

Limitations

• Python 3.11 only (nougat-ocr dependency constraint)
• Model weights: ~1.3 GB (auto-downloaded on first run)
• GPU strongly recommended for reasonable performance
• Supported formats: PDF, JPG, JPEG, PNG, WEBP, BMP, TIFF

License

MIT License - see LICENSE for details.