Anleitung

Docling installieren

Der vollständige, geprüfte Weg von null zur ersten Umwandlung — Python-Setup, pip vs. uv, virtuelle Umgebungen, alle optionalen Extras, PyTorch-CPU-/CUDA-/MPS-Builds, Tesseract-Systempakete, Modell-Downloads, Verifikation und Fehlerbehebung je Betriebssystem. Läuft auf macOS, Linux und Windows (x86_64 und arm64).

WindowsWindowsuv, pip, C++ Build Tools und WSL2-CUDA-Pfad.macOSmacOSApple Silicon und Intel, MPS-Beschleunigung, OcrMac, Homebrew-Tesseract.LinuxLinuxUbuntu/Debian/RHEL, CPU-Only-Wheels, CUDA 12.8/13.0, apt und dnf.ContainerDockerDie HTTP-API als Container betreiben: CPU- vs. CUDA-Images, Ports, UI, curl-Test.

Step 1

Welcher Installationsweg passt?

Situation	Hier starten	Warum
Lokale PDFs umwandeln	`pip install docling`	Kernpaket; kein Docker, kein Server nötig.
Unter Windows Compiler-Fehler	Windows-Anleitung + `uv add docling`	uv löst vorkompilierte Wheels auf und umgeht MSVC.
HTTP-API für eine App nötig	Docker-/docling-serve-Anleitung	Offizieller Container mit `/v1/convert/source`, `/docs`, `/ui`.
GPU-Tempo unter Linux nötig	Linux-Anleitung	CUDA-fähiges torch + `--device cuda`.
Auf einem Mac	macOS-Anleitung	Apple Silicon nutzt MPS; Intel braucht gepinntes torch.
Gescannte PDFs / OCR	Extras-Tabelle + OCR-Anleitung	RapidOCR, EasyOCR, Tesseract oder OcrMac wählen.

Step 2

Voraussetzungen (alle Plattformen)

Liegt die Ausgabe unter 3.10, zuerst ein neueres Python installieren — alles Folgende setzt 3.10+ voraus:

python --version && pip --version

Python 3.10 oder neuer, 64-bit. Python 3.9 wird seit Docling 2.70.0 nicht mehr unterstützt. Bei sehr neuen Python-Versionen ggf. den PyPI-Verlauf prüfen, falls noch kein Wheel existiert.
pip 23+ oder Astral uv. uv ist schneller und vermeidet die meisten Windows-Compilerprobleme.
ca. 2–4 GB freien Speicher für Modelle beim ersten Lauf (Layout-, Tabellen- und OCR-Modelle).
Funktionierendes Internet beim ersten Lauf, damit Modelle geladen werden können (für Offline-Rechner siehe Modell-Cache).
Optional: Tesseract-Systembinärdatei (nur für Tesseract-Engines), CUDA-Treiber (nur für NVIDIA-GPU), Docker (nur für docling-serve).

Step 3

Isolierte Umgebung anlegen (empfohlen)

Option A — venv + pip (überall): Unter Windows-PowerShell statt der source-Zeile .venv\Scripts\Activate.ps1 verwenden.

python -m venv .venv

source .venv/bin/activate

python -m pip install -U pip

Docling zieht PyTorch, ONNX- und OCR-Bibliotheken mit. Niemals ins System-Python installieren — ein einziges konfligierendes torch oder numpy kann andere Werkzeuge zerstören.

Option B — uv (schnellste Wahl, beste unter Windows):

uv venv --python 3.12

uv add docling

Step 4

Schnellinstallation: pip vs. uv

Standard (pip): Beide installieren dasselbe Paket von PyPI auf macOS, Linux und Windows (x86_64 + arm64). Die vollständige offizielle Anleitung steht in der offiziellen Installationsdokumentation.

pip install docling

uv add docling

Mit uv (löst vorkompilierte Wheels auf und vermeidet C++ Build Tools): siehe Befehl oben.

Step 5

Alle optionalen Extras im Überblick

Das Basispaket deckt die Standardumwandlung ab. Alles mit schweren Drittabhängigkeiten ist ein Extra: pip install "docling[NAME]" (kombinierbar mit Kommas: "docling[rapidocr,vlm]").

Extra	Was es hinzufügt	Installation
rapidocr	RapidOCR-Engine (ONNX-Runtime-Backend) — einfachstes plattformübergreifendes OCR	`pip install "docling[rapidocr]"`
easyocr	EasyOCR-Engine — reine Python-Installation, gute mehrsprachige Abdeckung	`pip install "docling[easyocr]"`
tesserocr	Schnelles Tesseract-Binding (braucht zuerst System-Tesseract, siehe unten)	`pip install "docling[tesserocr]"`
ocrmac	Apple-Vision-OCR — nur macOS	`pip install "docling[ocrmac]"`
vlm	Vision-Language-Model-Pipeline (u. a. Granite Docling)	`pip install "docling[vlm]"`
asr	Audio-Spracherkennungs-Pipeline (Whisper)	`pip install "docling[asr]"`
htmlrender	HTML-Seitenrendering für das HTML-Backend	`pip install "docling[htmlrender]"`
feat-ocr-nemotron	NVIDIA Nemotron OCR — nur Linux x86_64 + Python 3.12 + CUDA 13.x	`pip install "docling[feat-ocr-nemotron]" --extra-index-url https://download.pytorch.org/whl/cu130 --index-strategy unsafe-best-match`
mac_intel	Gepinntes torch für Intel-Macs (PyTorch ≥2.6 ohne Intel-Wheels)	`pip install "docling[mac_intel]"`

Bei der OCR-Wahl zählt: RapidOCR und EasyOCR installieren sich per pip allein; Tesseract-Varianten brauchen zuerst die Systembinärdatei. Engines vergleicht die OCR-Anleitung.

Step 6

PyTorch-Builds: CPU-only, CUDA, MPS, Intel-Macs

Docling-Modelle laufen auf PyTorch. Das Standard-Wheel passt für die meisten, drei Fälle brauchen einen Spezial-Build:

pip install docling --extra-index-url https://download.pytorch.org/whl/cpu

uv add torch==2.2.2 torchvision==0.17.2 docling

pip install "docling[mac_intel]"

Linux CPU-only-Server: Das kleine CPU-Build statt des großen CUDA-Wheels nehmen (siehe Befehl unten).
NVIDIA-GPU unter Linux/Windows: CUDA-fähiges torch für die eigene CUDA-Version installieren, dann mit --device cuda auswählen. Unter Windows ist WSL2 der einfachste CUDA-Weg — Details in der Windows-Anleitung.
macOS Intel (x86_64): PyTorch 2.6.0+ liefert keine Intel-Wheels. Letzten passenden Build pinnen und bei Python ≤3.12 bleiben.
Apple Silicon: Läuft direkt; bei Bedarf MPS-Backend mit --device mps wählen (siehe macOS-Anleitung).

Step 7

Tesseract-Systempakete + TESSDATA_PREFIX

Nur nötig bei einer Tesseract-Engine. Binärdatei vor dem pip-Extra mit dem OS-Paketmanager installieren, dann TESSDATA_PREFIX auf die Sprachdaten zeigen lassen (mit Schrägstrich am Ende):

BS	Installation	TESSDATA_PREFIX-Beispiel
macOS (Homebrew)	`brew install tesseract leptonica pkg-config`	`/opt/homebrew/share/tessdata/`
Ubuntu / Debian	`sudo apt-get install tesseract-ocr tesseract-ocr-eng libtesseract-dev libleptonica-dev pkg-config`	aus `dpkg -L tesseract-ocr-eng \| grep tessdata$`
RHEL / Fedora	`sudo dnf install tesseract tesseract-devel tesseract-langpack-eng tesseract-osd leptonica-devel`	`/usr/share/tesseract/tessdata/`
Windows	UB-Mannheim-Build installieren, zu PATH hinzufügen	`TESSDATA_PREFIX` auf dessen `tessdata\`-Ordner setzen

Falls sich tesserocr nicht bauen lässt: pip uninstall tesserocr, dann pip install --no-binary :all: tesserocr.

Step 8

Installation prüfen

Diese drei Prüfungen in Reihenfolge ausführen — jede grenzt eine andere Fehlerebene ab. Für den ersten Test ein kleines digitales (Text-)PDF nehmen, damit OCR und GPU außen vor bleiben. Danach --to json, --to html und --ocr-engine rapidocr probieren. Bei Fehlern den Abschnitt 11 oder die Fehlerbehebung heranziehen.

docling --help

python -c "import docling; print(docling.__version__)"

docling convert sample.pdf --to md

Step 9

Erster Lauf lädt Modelle — einplanen

docling-tools models download --all

Der erste Durchlauf lädt Layout-, Tabellenstruktur- und OCR-Modelle — einmal langsam, danach schnell.
Für diesen Lauf eine stabile Verbindung behalten; ein abgebrochener Download hinterlässt einen defekten Cache — einfach erneut laufen lassen.
Alles vorab laden:
Den Cache per DOCLING_CACHE_DIR auf eine beschreibbare Platte zeigen lassen, falls der Standardspeicherort schreibgeschützt oder zu klein ist.
Rechner ohne Netz: Cache auf einem verbundenen Rechner laden und das Verzeichnis kopieren.

Step 10

Aktualisieren, pinnen und deinstallieren

In Produktion eine exakte Version pinnen (requirements.txt, Lockfile oder Container-Tag), damit kein Modell- oder CLI-Wechsel überrascht. Diese Seite ist gegen die Version im Badge unten verifiziert.

pip install -U docling

pip install "docling==2.129.0"

pip uninstall docling

Step 11

Die 5 häufigsten Installationsfehler beheben

Microsoft Visual C++ 14.0 is required (Windows): Zu uv add docling für vorkompilierte Wheels wechseln oder Build Tools per winget install Microsoft.VisualStudio.2022.BuildTools mit C++-Workload installieren. Details in der Windows-Anleitung und der Fehlerbehebung.
Python-Versionsfehler: Frische Umgebung mit 3.10–3.12 anlegen (uv venv --python 3.12). Python 3.9 wird seit 2.70.0 nicht unterstützt.
OCR-Extra scheitert: rapidocr oder easyocr nehmen (nur pip); für Tesseract zuerst Systembinärdatei + TESSDATA_PREFIX.
GPU wird ignoriert (läuft auf CPU): Prüfen, dass torch.cuda.is_available() True liefert, CUDA-torch installieren, --device cuda übergeben (MPS auf Apple Silicon).
Speicher voll / sehr langsam: Dateien einzeln umwandeln, --num-threads senken, --no-ocr für digitale PDFs.

Step 12

Installations-FAQ

Welche Python-Version braucht Docling?

Python 3.10 oder neuer, 64-bit. Der Support für 3.9 endete mit 2.70.0. Bei 3.9 oder 32-bit-Build eine neue Umgebung mit 3.10–3.12 anlegen und neu installieren.

pip oder uv — was soll ich nehmen?

Beide installieren dasselbe Paket. uv löst vorkompilierte Wheels aggressiver auf, umgeht so den MSVC-Compilerfehler unter Windows und ist überall schneller. Mit uv: uv add docling, sonst reicht pip install docling.

Brauche ich Docker?

Nein für die lokale Umwandlung — das Python-Paket genügt. Docker (oder Podman) ist nur für docling-serve nötig, den HTTP-API-Server als Container. Siehe die Docker-Anleitung.

Brauche ich eine GPU?

Nein. Alles läuft auf CPU. Eine CUDA-GPU (Linux/Windows) oder MPS (Apple Silicon) beschleunigt Layoutanalyse, Tabellen und OCR bei langen Dokumenten deutlich.

Warum ist die erste Umwandlung so langsam?

Docling lädt beim ersten Einsatz seine Modelle. Verbindung für diesen Lauf halten oder mit docling-tools models download --all vorab laden. Spätere Läufe nutzen den Cache.

Welche OCR-Engine installiert sich am einfachsten?

RapidOCR (docling[rapidocr]) oder EasyOCR (docling[easyocr]) — beide rein per pip. Tesseract ist exzellent, braucht aber Systembinärdatei plus Sprachdaten; OcrMac läuft nur auf macOS.

Kann ich Docling offline installieren?

Ja, mit Vorbereitung: Wheels plus Modell-Cache auf einem verbundenen Rechner laden, beides übertragen. Auf dem Offline-Rechner DOCLING_CACHE_DIR auf den kopierten Cache zeigen lassen.

Wie nutze ich Docling mit RAG-Frameworks?

Erst Docling installieren, dann den Framework-Adapter (LangChain, LlamaIndex, Haystack). Nach Markdown oder JSON umwandeln, dann chunken und embedden. Siehe RAG-Anleitung und Beispiele.

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