Should I use pip or uv to install Docling?

Both work. uv resolves pre-compiled wheels more reliably and avoids most C++ compiler errors on Windows, so prefer uv add docling there.

Do I need Docker to use Docling?

No. Install the Python package for local conversion. Use Docker only when you want the docling-serve HTTP API as a container.

Why is the first conversion slow?

The first run downloads layout, table and OCR models. Keep a working connection for the first conversion or pre-download models.

Guide

Install Docling

The complete, verified path from zero to your first conversion — Python setup, pip vs uv, virtual environments, every optional extra, PyTorch CPU / CUDA / MPS builds, Tesseract system packages, model downloads, verification and per-OS fixes. Works on macOS, Linux and Windows (x86_64 and arm64).

bash — install in 30 seconds

$python -m venv .venv && source .venv/bin/activate

$pip install docling

$docling convert sample.pdf --to md

✓Python 3.10+ (64-bit) on Windows, macOS & Linux. Prefer uv on Windows for pre-built wheels.

✓~2–4 GB for first-run models, then fast & fully offline.

✓CPU works everywhere; CUDA / MPS only adds speed.

WindowsWindows 10 / 11uv vs pip, 64-bit Python, C++ Build Tools, winget fixes, WSL2 + CUDA path. macOSmacOSApple Silicon + Intel, MPS acceleration, OcrMac, Homebrew Tesseract. LinuxLinuxUbuntu / Debian / RHEL, CPU-only wheels, CUDA 12.8 / 13.0, apt + dnf. ContainerDocker / docling-serveServe the HTTP API as a container: CPU vs CUDA images, ports, UI, curl test.

Choose your path

Which install path should you choose?

Your situation	Start here	Why
Just want to convert PDFs locally	`pip install docling`	Core package; no Docker, no server needed.
On Windows and hitting compiler errors	Windows guide + `uv add docling`	uv resolves pre-built wheels and skips MSVC.
Need an HTTP API for an app	Docker / docling-serve guide	Official container exposes `/v1/convert/source`, `/docs`, `/ui`.
Need GPU speed on Linux	Linux guide	CUDA-enabled torch + `--device cuda`.
On a Mac	macOS guide	Apple Silicon uses MPS; Intel needs pinned torch.
Scanned PDFs / OCR	Extras table + OCR guide	Pick RapidOCR, EasyOCR, Tesseract or OcrMac.

Before you start

Requirements (all platforms)

Python 3.10 or newer, 64-bit. Python 3.9 support was dropped in Docling 2.70.0. Very new Python releases may lag until Docling adds wheels — check the PyPI release history if your version has no wheel.
pip 23+ or Astral uv. uv is faster and avoids most Windows compiler issues.
~2–4 GB free disk for models on first run (layout, table structure, OCR models).
Working internet on first run so models can download (see model cache for offline machines).
Optional: Tesseract system binary (only if you choose a Tesseract engine), CUDA drivers (only for NVIDIA GPU), Docker (only for docling-serve).

python --version && pip --version

ⓘIf that prints anything below 3.10, install a newer Python first — everything below assumes 3.10+.

Isolate dependencies

Create an isolated environment (recommended)

Docling pulls in PyTorch, ONNX and OCR libraries. Never install it into your system Python — one conflicting torch or numpy can break other tools. Pick one:

Option A — venv + pip (everywhere)

python -m venv .venv

source .venv/bin/activate

Option B — uv (fastest, best on Windows)

uv venv --python 3.12

uv add docling

ⓘOn Windows PowerShell use .venv\Scripts\Activate.ps1 instead of the source line.

Install the package

Quick install: pip vs uv

Standard (pip):

pip install docling

With uv (resolves pre-compiled wheels, avoids C++ build tools):

uv add docling

Both install the same package from PyPI on macOS, Linux and Windows (x86_64 + arm64). For the full official instructions see the official installation docs.

Add capabilities

Every optional extra, explained

The base package covers default conversion. Anything needing heavy third-party deps ships as an extra, installed with pip install "docling[NAME]" (combine with commas: "docling[rapidocr,vlm]").

Extra	What it adds	Install
rapidocr	RapidOCR engine (ONNX Runtime backend) — easiest cross-platform OCR	`pip install "docling[rapidocr]"`
easyocr	EasyOCR engine — pure-Python install, good multilingual coverage	`pip install "docling[easyocr]"`
tesserocr	Fast Tesseract binding (needs system Tesseract first, see below)	`pip install "docling[tesserocr]"`
ocrmac	Apple Vision OCR — macOS only	`pip install "docling[ocrmac]"`
vlm	Vision-language-model pipeline deps (Granite Docling etc.)	`pip install "docling[vlm]"`
asr	Audio-speech-recognition pipeline (Whisper)	`pip install "docling[asr]"`
htmlrender	HTML page rendering for the HTML backend	`pip install "docling[htmlrender]"`
feat-ocr-nemotron	NVIDIA Nemotron OCR — Linux x86_64 + Python 3.12 + CUDA 13.x only	`pip install "docling[feat-ocr-nemotron]" --extra-index-url https://download.pytorch.org/whl/cu130 --index-strategy unsafe-best-match`
mac_intel	Pinned torch compatible with Intel Macs (PyTorch ≥2.6 drops Intel wheels)	`pip install "docling[mac_intel]"`

ⓘOCR engine choice matters: RapidOCR and EasyOCR install with pip alone; Tesseract variants need the system binary first. Compare engines in the OCR guide.

Acceleration

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

Docling models run on PyTorch. The default wheel works for most people, but three cases need a special build:

Linux CPU-only servers: avoid the large CUDA wheel and install the small CPU build:

pip install docling --extra-index-url https://download.pytorch.org/whl/cpu
uv users pin torch to the CPU index in pyproject.toml (see the Linux guide for the exact snippet).
NVIDIA GPU on Linux/Windows: install a CUDA-enabled torch for your CUDA version, then select it with --device cuda. WSL2 is the simplest CUDA path on Windows — full steps in the Windows guide.
macOS Intel (x86_64): PyTorch 2.6.0+ ships no Intel wheels. Pin the last good build and stay on Python ≤3.12:
uv add torch==2.2.2 torchvision==0.17.2 docling
or
pip install "docling[mac_intel]"
Apple Silicon: works out of the box; select the MPS backend with --device mps when needed (see the macOS guide).

System dependency

Tesseract system packages + TESSDATA_PREFIX

Only needed if you pick a Tesseract engine. Install the binary with your OS package manager before the pip extra, then point TESSDATA_PREFIX at the language data (note the trailing slash):

OS	Install	TESSDATA_PREFIX example
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`	from `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	Install UB Mannheim build, add to PATH	set `TESSDATA_PREFIX` to its `tessdata\` folder

!If tesserocr fails to build, try pip uninstall tesserocr then pip install --no-binary :all: tesserocr.

Confirm it works

Verify your installation

Run these three checks in order — each one isolates a different failure layer:

docling --help

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

docling convert sample.pdf --to md

✓Use a small digital (text) PDF for the first test so OCR and GPU are out of the equation. Then try --to json, --to html, and --ocr-engine rapidocr to confirm each layer. If any step fails, match the error in section 11 or the troubleshooting reference.

Cache & offline

First run downloads models — plan for it

The first conversion downloads layout, table-structure and OCR models — expect it to be slow once, then fast.
Keep a stable connection for that first run; a partial download leaves a broken cache — just re-run.
Pre-download everything ahead of time with
docling-tools models download --all
Point the cache at a writable disk with DOCLING_CACHE_DIR if the default location is read-only or too small.
Air-gapped machines: download on a connected host, then copy the cache directory over.

Stay current

Upgrade, pin and uninstall

pip install -U docling

pip install "docling==2.129.0"

pip uninstall docling

ⓘPin an exact version in production (requirements.txt, lockfile or container tag) so a model or CLI change cannot surprise you. This site is verified against the version in the badge below.

Troubleshoot

Fix the 5 most common install failures

Microsoft Visual C++ 14.0 is required (Windows): switch to uv add docling for pre-built wheels, or install Build Tools via winget install Microsoft.VisualStudio.2022.BuildTools with the C++ workload. Details in the Windows guide and troubleshooting.
Python version errors: create a fresh env with 3.10–3.12 (uv venv --python 3.12). Python 3.9 is unsupported since 2.70.0.
OCR extra fails: use rapidocr or easyocr (pip-only); for Tesseract install the system binary + TESSDATA_PREFIX first.
GPU ignored (runs on CPU): confirm torch.cuda.is_available() is True, install a CUDA torch, pass --device cuda (MPS on Apple Silicon).
Out of memory / very slow: convert one file at a time, lower --num-threads, add --no-ocr for digital PDFs.

Answers

Installation FAQ

What Python version does Docling need?

Python 3.10 or newer, 64-bit. Support for 3.9 was dropped in 2.70.0. If you are on 3.9 or a 32-bit build, create a new environment with 3.10–3.12 and reinstall.

pip or uv — which should I use?

Both install the same package. uv resolves pre-compiled wheels more aggressively, so it avoids the MSVC compiler error on Windows and is faster everywhere. Use uv add docling if you already use uv; otherwise pip install docling is fine.

Do I need Docker?

No for local conversion — the Python package is enough. You need Docker (or Podman) only to run docling-serve, the HTTP API server, as a container. See the Docker guide.

Do I need a GPU?

No. Everything runs on CPU. A CUDA GPU (Linux/Windows) or MPS (Apple Silicon) makes layout analysis, tables and OCR noticeably faster on long documents.

Why is the first conversion so slow?

Docling downloads its models on first use. Keep the connection alive for that run, or pre-download with docling-tools models download --all. Later runs reuse the cache.

Which OCR engine installs most easily?

RapidOCR (docling[rapidocr]) or EasyOCR (docling[easyocr]) — both are pip-only. Tesseract is excellent but needs a system binary plus language data; OcrMac only works on macOS.

Can I install Docling offline?

Yes with preparation: install wheels plus the model cache on a connected machine, then transfer both. Set DOCLING_CACHE_DIR to the copied cache on the offline host.

How do I use Docling with RAG frameworks?

Install Docling first, then add the framework adapter (LangChain, LlamaIndex, Haystack). Convert to Markdown or JSON, then chunk and embed. See the RAG guide and examples.

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

GuideWindows 10 / 11 →uv, MSVC fix, WSL2 + CUDA. GuidemacOS →Apple Silicon, MPS, OcrMac. GuideLinux →CPU wheels, CUDA, apt/dnf. GuideDocker →docling-serve API & images. FixTroubleshooting →Install, GPU, OCR & conversion errors. ReferenceCommand finder →Copy-paste CLI commands. ReferenceOCR engines →Compare RapidOCR, Tesseract & more. ToolConfig generator →Build CLI & Python snippets.