Install

Install Docling on macOS

Apple Silicon (M1/M2/M3/M4) and Intel Macs with Python 3.10+. Verify each command against the official installation docs.

bash — quickstart

$pip install docling

$docling convert report.pdf --device mps

✓

Check your chip — run uname -m: arm64 is Apple Silicon, x86_64 is Intel.

⚡

MPS on Apple Silicon — CPU works by default; add --device mps for GPU speed.

Intel torch pin — newer torch has no Intel wheels; pin torch 2.2.2 on Python ≤3.12.

Check

Which Mac do you have?

uname -m

arm64 → Apple Silicon. Follow sections 2–6. MPS acceleration is available.
x86_64 → Intel. Follow sections 2–3, then section 7 before installing extras — newer torch wheels do not exist for Intel.

Python

Python setup (both chips)

Install Python 3.10–3.12 from python.org or brew install python@3.12.
Always use a venv:

Intel Macs: stay on Python ≤3.12 — PyTorch 2.2.2 (the last Intel-compatible build) requires it.

python3 --version

python3 -m venv .venv && source .venv/bin/activate

python -m pip install -U pip

Install

Base install

pip install docling

uv alternative: uv add docling (or uv pip install docling inside the venv).

Accelerate

Apple Silicon + MPS acceleration

Apple Silicon runs Docling on PyTorch’s MPS (Metal) backend instead of CUDA. CPU is the default and works fine; select MPS when you want GPU speed:

docling convert report.pdf --device mps

docling convert report.pdf --device auto

Check availability from Python:

python -c "import torch; print(torch.backends.mps.is_available())"

If that prints False, update macOS + torch; some OCR engines are CPU-only regardless of this flag.

OCR

OcrMac: native Apple Vision OCR

macOS-only extra using the built-in Apple Vision framework — no Tesseract binary needed, private on-device OCR:

pip install "docling[ocrmac]"

docling convert scan.pdf --ocr-engine ocrmac --ocr-mode full_page

Use it for English/European scans on modern macOS. For CJK or script-heavy scans, compare with RapidOCR/EasyOCR in the OCR guide.

OCR

Tesseract via Homebrew

Only needed for the Tesseract engines (tesserocr, CLI). Install the binary first:

brew install tesseract leptonica pkg-config

pip install "docling[tesserocr]"

TESSDATA_PREFIX=/opt/homebrew/share/tessdata/ docling convert scan.pdf --ocr-engine tesseract

TESSDATA_PREFIX must end with a slash and point at the folder containing .traineddata files. On Intel Homebrew the prefix is usually /usr/local/share/tessdata/. Persist it with export TESSDATA_PREFIX=… in your shell profile.

Intel

Intel Macs: the torch pin

Why: PyTorch 2.6.0+ publishes no wheels for Intel macOS, so a plain pip install docling can fail resolving torch. Two supported workarounds (Python ≤3.12 required):

uv add torch==2.2.2 torchvision==0.17.2 docling

pip install "docling[mac_intel]"

If you already installed a broken torch, remove it first (pip uninstall torch torchvision) and reinstall with one of the lines above.

Test

Verify

docling --help

docling convert sample.pdf --to md

Then confirm your accelerator and OCR layers separately: --device mps on Apple Silicon, --ocr-engine ocrmac or rapidocr on a scanned page.

Fix

Common macOS problems

torch fails on Intel — apply the section-7 pin; do not use Python 3.13+ on Intel.
TesseractNotFound / missing languages — reinstall via Homebrew, set TESSDATA_PREFIX (trailing slash), see OCR package installation error.
OcrMac import error — the extra only works on macOS with a recent OS; reinstall "docling[ocrmac]" inside the venv.
MPS not used — confirm torch.backends.mps.is_available(); some stages fall back to CPU by design.
SSL / cert errors on first model download — update Python certs (Install Certificates.command from the python.org installer) and re-run.

FAQ

macOS FAQ

M-series or Intel — does it matter?

Yes for two things: Apple Silicon can use --device mps and the OcrMac extra; Intel Macs must pin torch 2.2.2 and stay on Python ≤3.12. Everything else is identical.

Should I use OcrMac or Tesseract?

OcrMac is zero-setup and private (on-device Vision). Tesseract gives more language/script control but needs Homebrew + TESSDATA_PREFIX. RapidOCR is a good pip-only middle ground.

Do I need Xcode?

No. Only the Xcode command-line tools are occasionally needed if pip builds something: xcode-select --install.

python vs python3?

Inside the venv both point to the same interpreter. Outside it, macOS reserves python — always use python3 -m venv and activate before installing.

InstallInstall overviewCompare pip, uv, Docker and other platforms. OCROCR enginesOcrMac, Tesseract, RapidOCR and engine modes. ReferenceCommandsFind convert, verify and batch commands. HelpTroubleshootingFix install, GPU and OCR errors.

Verified with Docling v2.129.0 · Last checked 2026-09-22 · Official source