Installieren

Docling auf macOS installieren

Apple Silicon (M1/M2/M3/M4) und Intel-Macs mit Python 3.10+. Jeden Befehl mit der offiziellen Installationsdokumentation abgleichen.

Step 1

Welchen Mac haben Sie?

uname -m

arm64 → Apple Silicon. Abschnitte 2–6 folgen. MPS-Beschleunigung verfügbar.
x86_64 → Intel. Abschnitte 2–3 folgen, dann Abschnitt 7 vor dem Installieren von Extras — neuere torch-Wheels existieren nicht für Intel.

Step 2

Python-Setup (beide Chips)

python3 --version

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

python -m pip install -U pip

Python 3.10–3.12 von python.org oder per brew install python@3.12 installieren.
Intel-Macs: Bei Python ≤3.12 bleiben — PyTorch 2.2.2 (letzter Intel-kompatibler Build) verlangt es.
Immer ein venv nutzen:

Step 3

Basisinstallation

uv-Alternative: uv add docling (oder uv pip install docling im venv).

pip install docling

Step 4

Apple Silicon + MPS-Beschleunigung

Apple Silicon lässt Docling auf PyTorchs MPS-Backend (Metal) statt CUDA laufen. CPU ist Standard und funktioniert gut; für GPU-Tempo MPS wählen. Falls das False ausgibt, macOS + torch aktualisieren; manche OCR-Engines sind ohnehin CPU-only.

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: natives Apple-Vision-OCR

macOS-eigenes Extra mit eingebautem Apple-Vision-Framework — keine Tesseract-Binärdatei nötig, privates On-Device-OCR. Für Englisch/europäische Scans auf modernem macOS. Für CJK oder schriftlastige Scans mit RapidOCR/EasyOCR in der OCR-Anleitung vergleichen.

pip install "docling[ocrmac]"

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

Step 6

Tesseract via Homebrew

Nur für Tesseract-Engines (tesserocr, CLI). Binärdatei zuerst installieren. TESSDATA_PREFIX muss mit Schrägstrich enden und auf den Ordner mit .traineddata-Dateien zeigen. Auf Intel-Homebrew meist /usr/local/share/tessdata/. Per export TESSDATA_PREFIX=… im Shell-Profil dauerhaft setzen.

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-Macs: der torch-Pin

Warum: PyTorch 2.6.0+ veröffentlicht keine Wheels für Intel-macOS, daher kann ein schlichtes pip install docling an torch scheitern. Zwei unterstützte Wege (Python ≤3.12 nötig). Falls schon ein defektes torch installiert ist, erst entfernen (pip uninstall torch torchvision) und mit einer Zeile oben neu installieren.

uv add torch==2.2.2 torchvision==0.17.2 docling

pip install "docling[mac_intel]"

Step 8

Verifikation

Danach Beschleuniger- und OCR-Schichten getrennt bestätigen: --device mps auf Apple Silicon, --ocr-engine ocrmac oder rapidocr auf einer gescannten Seite.

docling --help

docling convert sample.pdf --to md

Step 9

Häufige macOS-Probleme

torch scheitert auf Intel — Pin aus Abschnitt 7 anwenden; auf Intel kein Python 3.13+.
TesseractNotFound / fehlende Sprachen — per Homebrew neu installieren, TESSDATA_PREFIX setzen (Schrägstrich am Ende), siehe OCR-Paket-Installationsfehler.
OcrMac-Importfehler — das Extra läuft nur auf macOS mit aktuellem OS; "docling[ocrmac]" im venv neu installieren.
MPS wird nicht genutzt — torch.backends.mps.is_available() prüfen; manche Stufen fallen konstruktionsbedingt auf CPU zurück.
SSL-/Zertifikatsfehler beim ersten Modell-Download — Python-Zertifikate aktualisieren (Install Certificates.command aus dem python.org-Installer) und erneut laufen lassen.

Step 10

macOS-FAQ

M-Serie oder Intel — macht das einen Unterschied?

Ja, bei zwei Dingen: Apple Silicon kann --device mps und das OcrMac-Extra nutzen; Intel-Macs müssen torch 2.2.2 pinnen und bei Python ≤3.12 bleiben. Alles andere ist identisch.

OcrMac oder Tesseract?

OcrMac ist ohne Setup und privat (Vision auf dem Gerät). Tesseract gibt mehr Sprach-/Schriftkontrolle, braucht aber Homebrew + TESSDATA_PREFIX. RapidOCR ist eine gute pip-eigene Mitte.

Brauche ich Xcode?

Nein. Nur die Xcode-Kommandozeilenwerkzeuge sind gelegentlich nötig, falls pip etwas baut: xcode-select --install.

python oder python3?

Im venv zeigen beide auf denselben Interpreter. Außerhalb reserviert macOS python — immer python3 -m venv nutzen und vor dem Installieren aktivieren.

Verifiziert mit Docling v2.129.0 · Zuletzt geprüft 2026-09-22 · Offizielle Quelle