導入

macOSへのDocling導入

Apple Silicon (M1/M2/M3/M4) とIntel Mac + Python 3.10以降。各コマンドは公式インストール文書と照合。

Step 1

自分のMacを確認

uname -m

arm64 → Apple Silicon。2〜6節へ。MPS高速化あり。
x86_64 → Intel。2〜3節の後、エクストラ導入前に7節へ。新型torch WheelはIntelに存在しない。

Step 2

Python設定 (両チップ)

python3 --version

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

python -m pip install -U pip

Python 3.10〜3.12をpython.orgかbrew install python@3.12で。
Intel Mac: Python 3.12以下に留める (PyTorch 2.2.2最終Intel対応版の要求)。
必ずvenv利用:

Step 3

基本導入

uv代替: uv add docling (またはvenv内でuv pip install docling)。

pip install docling

Step 4

Apple Silicon + MPS高速化

Apple SiliconではCUDAではなくPyTorchのMPS (Metal) バックエンドで動作。既定CPUでも十分。GPU速度が欲しければMPS指定。FalseならmacOS + torch更新。一部OCRは元々CPU専用。

docling convert report.pdf --device mps

docling convert report.pdf --device auto

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

Step 5

OcrMac: Apple VisionネイティブOCR

内蔵Apple Vision利用のmacOS専用エクストラ。Tesseract本体不要のオンデバイス非公開OCR。現行macOSでの英語・欧州スキャン向け。CJKや複雑文字はOCRガイドでRapidOCR/EasyOCR比較を。

pip install "docling[ocrmac]"

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

Step 6

HomebrewでTesseract

Tesseract系 (tesserocr・CLI) のみ必要。本体を先に導入。TESSDATA_PREFIXは末尾/付きで.traineddataフォルダへ。Intel Homebrewでは概ね/usr/local/share/tessdata/。シェル設定にexport TESSDATA_PREFIX=…で永続化。

brew install tesseract leptonica pkg-config

pip install "docling[tesserocr]"

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

Step 7

Intel Mac: torch固定

理由: PyTorch 2.6.0以降はIntel macOS用Wheelを出さないため、素のpip install doclingがtorch解決で失敗し得る。対応2択 (Python 3.12以下必須)。壊れたtorchが既に入っていれば削除 (pip uninstall torch torchvision) 後に上記いずれかで再導入。

uv add torch==2.2.2 torchvision==0.17.2 docling

pip install "docling[mac_intel]"

Step 8

検証

次に加速器とOCRを分けて確認。Apple Siliconで--device mps、スキャンページで--ocr-engine ocrmacかrapidocr。

docling --help

docling convert sample.pdf --to md

Step 9

macOS頻出問題

Intelでtorch失敗 — 7節の固定を適用。IntelでPython 3.13以降は不可。
TesseractNotFound・言語欠落 — Homebrew再導入とTESSDATA_PREFIX (末尾/) 設定。OCR導入エラー参照。
OcrMacインポートエラー — 現行macOS専用。venv内で"docling[ocrmac]"再導入。
MPS未使用 — torch.backends.mps.is_available()確認。一部段階は仕様上CPUに退行。
初回取得でSSL/証明書エラー — Python証明書更新 (python.org版のInstall Certificates.command) 後再実行。

Step 10

macOS FAQ

M系とIntelで違いは?

2点。Apple Siliconは--device mpsとOcrMac利用可。Intelはtorch 2.2.2固定 + Python 3.12以下必須。他は同一。

OcrMacとTesseractどちら?

OcrMacはゼロ設定・非公開 (デバイス内Vision)。Tesseractは言語・文字制御が細かいがHomebrew + TESSDATA_PREFIX要。pipのみの中庸がRapidOCR。

Xcodeは必要?

不要。pipビルド時のみコマンドラインツールが必要な場合あり: xcode-select --install。

pythonとpython3?

venv内では同一。外ではmacOSがpythonを予約。常にpython3 -m venvし有効化後に導入。

Docling v2.129.0で検証 · 最終確認 2026-09-22 · 公式ソース