安装

在 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 节，再在安装 extra 之前看第 7 节——新版 torch Wheel 无 Intel 版。

Step 2

Python 配置（两种芯片）

python3 --version

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

python -m pip install -U pip

从 python.org 或以 brew install python@3.12 安装 Python 3.10–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 上 Docling 跑在 PyTorch MPS（Metal）后端而非 CUDA。默认 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 专属 extra，无需 Tesseract 可执行文件，设备端私有 OCR。适合新版 macOS 上的英文/欧洲扫描件。中文日韩或复杂文字请在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=… 写入 shell 配置持久化。

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 解析。两种官方 workaround（要求 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 导入报错——该 extra 仅新版 macOS 可用；在 venv 内重装 "docling[ocrmac]"。
MPS 未被使用——检查 torch.backends.mps.is_available()；部分阶段按设计回落 CPU。
首次模型下载报 SSL/证书错——更新 Python 证书（python.org 安装包的 Install Certificates.command）再跑。

Step 10

macOS FAQ

M 系还是 Intel，有差别吗？

两处有：Apple Silicon 可用 --device mps 与 OcrMac extra；Intel Mac 须锁定 torch 2.2.2 并停留 Python ≤3.12。其余完全相同。

OcrMac 还是 Tesseract？

OcrMac 零配置且私有（设备端 Vision）。Tesseract 语言/文字控制更细，但需 Homebrew + TESSDATA_PREFIX。RapidOCR 是不错的纯 pip 中间路线。

需要 Xcode 吗？

不需要。仅当 pip 需编译时偶需命令行工具：xcode-select --install。

python 还是 python3？

venv 内两者同一解释器。之外 macOS 保留 python，请一律 python3 -m venv 并激活后再装。

已按 Docling v2.129.0 验证 · 最近检查 2026-09-22 · 官方来源