When creating searchable PDFs, you can control how the Vision framework analyzes pages using --ocr-strategy.

• standard: Uses full-page OCR only.
• partitioned: Recursively splits large pages into smaller regions along their longer axis. This helps recover small text (like form labels) that might be missed during a single full-page pass. This mode may take longer as regions are processed serially.
• auto (default): Starts with a full-page pass, then runs a partitioned pass only for large pages where text is small or missing.

Constraints:

• partitioned mode cannot be combined with --roi (Region of Interest).
• auto mode skips partitioning if --roi is set.

# Force partitioned OCR for better accuracy on small text
mac-ocr searchable-pdf --ocr-strategy partitioned scan.pdf

The ocr() function calls run one at a time. A large Promise.all() burst will not increase throughput; use a serial loop or an application-level concurrency limit instead.

Queue Limits:

• The waiting queue accepts up to 512 calls.
• The queue has a 64 MiB memory budget.
• If the limit is exceeded, calls reject with a MacOcrError with code: 'queue_capacity_exceeded'.

You can install mac-ocr globally via npm to use it as a command-line tool, or run it on-demand using npx.

Requirements: macOS 10.15+. The package includes a prebuilt universal binary, so no Xcode or Swift toolchain is required.

npm install -g mac-ocr

Or run without installing

npx mac-ocr receipt.jpg

OCR is the default action for the mac-ocr command. It supports images, multi-page PDFs, stdin, and URLs.

By default, the output is plain text sent to stdout. You can request structured data using the --format flag:

• text (default): Plain text.
• json: Detailed output including bounding boxes, confidence, and page metadata.
• jsonl: One JSON object per page, streamed (ideal for large PDFs).

Examples:

mac-ocr receipt.jpg                 # text → stdout
mac-ocr page1.png page2.png         # multiple images
mac-ocr scan.pdf                    # multi-page PDF
cat screenshot.png | mac-ocr        # stdin
mac-ocr https://example.com/a.png   # URL (simple GET)

# Structured output
mac-ocr receipt.jpg --format json
mac-ocr document.pdf --format jsonl

By default, results are sent to stdout. Use -o, --output <dest> to save to files.

Modes:

• Fixed path: -o notes.txt (One file, single input only).
• Directory mode: -o out/ (Creates out/<input>.txt per input).
• Template mode: -o '[name].md' (Renders a unique filename per input). Note: Always quote template arguments in shells like zsh to avoid glob expansion.

Template Placeholders:

• [name]: Input filename without extension.
• [ext]: Input filename extension without the dot.
• [dir]: Input directory.
• [page]: 1-based page number (use this to write one file per page).
• [pagecount]: Total page count.

Example:

# Save recognized text as Markdown files next to the inputs
mac-ocr scans/*.pdf -o '[name].md'

mac-ocr scan.pdf -o notes.md
mac-ocr scans/*.pdf -o '[name].md'

To use the Node.js API, install the package using npm. Note that this library is macOS only and requires Node.js version 22 or higher with ESM enabled.

npm install mac-ocr

To diagnose OCR accuracy and geometry, set the environment variable MAC_OCR_DEBUG=1.

What happens in Debug Mode:

• Visual Overlays: The generated PDF will include visible colored boxes:
  • Red: Accepted line boxes.
  • Blue: Word boxes.
  • Orange: Rejected observations.
• Sidecar Data: A JSONL file is created next to the output PDF (e.g., lease.pdf $\rightarrow$ lease.jsonl). Each line contains detailed metadata for one page, including OCR geometry, recognition passes, and confidence values.

Note: Debug mode requires file output and will fail if using -o - (stdout).

Use the -o or --output flag to save recognized text to a file, a directory, or a filename template.

Templates:

• [name]: Original filename without extension.
• [ext]: Original extension.
• [dir]: Original directory.
• [page]: Page number.

Note: When using templates in shells like zsh, wrap the template in quotes to avoid globbing errors.

Examples:

# Save a .txt file next to each image
mac-ocr ~/Screenshots/*.png -o '[dir]/[name].txt'

# Save all recognized text from a PDF to a single file
mac-ocr scan.pdf -o notes.md

# Save outputs to a specific directory
mac-ocr receipts/*.pdf -o out/

The mac-ocr CLI provides text recognition (OCR) for images and PDFs. It supports file paths, stdin (via -), and HTTP(S) URLs (capped at 100 MiB). Multiple inputs are processed in order. PDFs are detected by magic bytes and honor EXIF orientation for width, height, and bounding box reporting.

Basic Usage:

• Recognize text from a file: mac-ocr image.png
• Recognize text from a PDF: mac-ocr document.pdf
• Process multiple files: mac-ocr file1.jpg file2.png
• Use piped stdin: cat image.png | mac-ocr
• Use a URL: mac-ocr https://example.com/image.png

mac-ocr receipt.jpg
mac-ocr scan.pdf --format jsonl
mac-ocr a.png b.png c.png
cat shot.png | mac-ocr
mac-ocr https://example.com/sign.png