指南

安装 Docling

从零到首次转换的完整验证路线——Python 配置、pip 与 uv、虚拟环境、全部可选 extra、CPU/CUDA/MPS 版 PyTorch、Tesseract 系统包、模型下载、验证与分系统排错。支持 macOS、Linux 与 Windows（x86_64 与 arm64）。

WindowsWindowsuv、pip、C++ 构建工具与 WSL2 + CUDA 路线。macOSmacOSApple Silicon 与 Intel、MPS 加速、OcrMac、Homebrew 版 Tesseract。LinuxLinuxUbuntu/Debian/RHEL、纯 CPU Wheel、CUDA 12.8/13.0、apt 与 dnf。ContainerDocker以容器运行 HTTP API：CPU 与 CUDA 镜像、端口、UI、curl 测试。

Step 1

该选哪条安装路线？

情形	从这里开始	原因
仅本地转换 PDF	`pip install docling`	核心包即可；无需 Docker 与服务器。
Windows 下遇到编译器报错	Windows 指南 + `uv add docling`	uv 解析预编译 Wheel，绕开 MSVC。
应用需要 HTTP API	Docker / docling-serve 指南	官方容器提供 `/v1/convert/source`、`/docs`、`/ui`。
Linux 下需要 GPU 速度	Linux 指南	CUDA 版 torch + `--device cuda`。
使用 Mac	macOS 指南	Apple Silicon 用 MPS；Intel 需锁定 torch。
扫描版 PDF / OCR	extra 对照表 + OCR 指南	选用 RapidOCR、EasyOCR、Tesseract 或 OcrMac。

Step 2

前置要求（全平台）

若输出低于 3.10，请先安装新版 Python——以下全部默认 3.10+：

python --version && pip --version

Python 3.10 及以上，64 位。 Docling 2.70.0 起不再支持 Python 3.9。若使用很新的 Python 且尚无 Wheel，请查阅 PyPI 历史。
pip 23+ 或 Astral uv。 uv 更快，且能避开 Windows 下大多数编译器问题。
预留约 2–4 GB 空间，供首次运行下载模型（版式、表格与 OCR 模型）。
首次运行需有效联网以下载模型（离线机器见模型缓存）。
可选：Tesseract 系统可执行文件（仅 Tesseract 引擎）、CUDA 驱动（仅 NVIDIA GPU）、Docker（仅 docling-serve）。

Step 3

创建隔离环境（推荐）

方案 A——venv + pip（通用）：Windows PowerShell 中用 .venv\Scripts\Activate.ps1 代替 source 行。

python -m venv .venv

source .venv/bin/activate

python -m pip install -U pip

Docling 会带入 PyTorch、ONNX 与 OCR 库。切勿装进系统 Python——一个冲突的 torch 或 numpy 就可能破坏其他工具。

方案 B——uv（最快，Windows 下最优）：

uv venv --python 3.12

uv add docling

Step 4

快速安装：pip 与 uv

标准方式（pip）：两者从 PyPI 安装同一软件包，支持 macOS、Linux 与 Windows（x86_64 + arm64）。完整官方步骤见官方安装文档。

pip install docling

uv add docling

使用 uv（解析预编译 Wheel，避开 C++ 构建工具）：见上一条命令。

Step 5

全部可选 extra 详解

基础包覆盖标准转换。凡依赖较重的第三方功能均为 extra：pip install "docling[名称]"（逗号组合："docling[rapidocr,vlm]"）。

Extra	新增内容	安装
rapidocr	RapidOCR 引擎（ONNX Runtime 后端）——最省事的跨平台 OCR	`pip install "docling[rapidocr]"`
easyocr	EasyOCR 引擎——纯 Python 安装，多语言覆盖好	`pip install "docling[easyocr]"`
tesserocr	高速 Tesseract 绑定（须先装系统 Tesseract，见下）	`pip install "docling[tesserocr]"`
ocrmac	Apple Vision OCR——仅 macOS	`pip install "docling[ocrmac]"`
vlm	视觉语言模型流水线（含 Granite Docling）	`pip install "docling[vlm]"`
asr	音频语音识别流水线（Whisper）	`pip install "docling[asr]"`
htmlrender	HTML 后端的页面渲染	`pip install "docling[htmlrender]"`
feat-ocr-nemotron	NVIDIA Nemotron OCR——仅 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	Intel Mac 锁定版 torch（PyTorch ≥2.6 无 Intel Wheel）	`pip install "docling[mac_intel]"`

OCR 选型要点：RapidOCR 与 EasyOCR 仅需 pip；Tesseract 变体须先装系统可执行文件。引擎对比见OCR 指南。

Step 6

PyTorch 构建：纯 CPU、CUDA、MPS、Intel Mac

Docling 模型运行于 PyTorch。默认 Wheel 适合大多数人，三种情形需要专用构建：

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 服务器：选用小体积 CPU 构建，而非臃肿的 CUDA Wheel（见下命令）。
Linux/Windows 的 NVIDIA GPU：按自身 CUDA 版本安装对应 torch，再以 --device cuda 选用。Windows 下 WSL2 是最省事的 CUDA 路线，详见Windows 指南。
macOS Intel（x86_64）：PyTorch 2.6.0+ 不再发布 Intel Wheel。请锁定最后可用构建，并停留在 Python ≤3.12。
Apple Silicon：开箱即用；需要时以 --device mps 选用 MPS 后端（见macOS 指南）。

Step 7

Tesseract 系统包 + TESSDATA_PREFIX

仅选用 Tesseract 引擎时需要。先用系统包管理器安装可执行文件，再将 TESSDATA_PREFIX 指向语言数据（末尾须带 /）：

系统	安装	TESSDATA_PREFIX 示例
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`	由 `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 构建并加入 PATH	将 `TESSDATA_PREFIX` 指向其 `tessdata\\` 目录

若 tesserocr 构建失败：pip uninstall tesserocr，再 pip install --no-binary :all: tesserocr。

Step 8

验证安装

按序执行以下三项检查，每项隔离不同的故障层面。首次测试请用小型数字（文本）PDF，以排除 OCR 与 GPU。之后尝试 --to json、--to html 与 --ocr-engine rapidocr。失败时查阅第 11 节或排错指南。

docling --help

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

docling convert sample.pdf --to md

Step 9

首次运行会下载模型，请预留

docling-tools models download --all

首次转换下载版式、表格结构与 OCR 模型——仅慢一次，之后很快。
首次运行请保持稳定连接；下载中断会留下损坏缓存，重跑一次即可。
提前下载全部：
若默认位置只读或空间不足，以 DOCLING_CACHE_DIR 指定可写磁盘。
离线机器：先在联网机器下载，再整体复制缓存目录。

Step 10

升级、锁定与卸载

生产环境请锁定确切版本（requirements.txt、lockfile 或容器 tag），避免模型或 CLI 变更带来意外。本站以下方徽章中的版本为准进行验证。

pip install -U docling

pip install "docling==2.129.0"

pip uninstall docling

Step 11

修复 5 类最常见安装失败

Microsoft Visual C++ 14.0 is required（Windows）：改用 uv add docling 获取预编译 Wheel，或以 winget install Microsoft.VisualStudio.2022.BuildTools 安装构建工具并勾选 C++ 工作负载。详见Windows 指南与排错。
Python 版本报错：新建 3.10–3.12 环境（uv venv --python 3.12）。Python 3.9 自 2.70.0 起不受支持。
OCR extra 失败：选用 rapidocr 或 easyocr（仅 pip）；Tesseract 须先装系统可执行文件 + TESSDATA_PREFIX。
GPU 被忽略（跑在 CPU 上）：确认 torch.cuda.is_available() 为 True，安装 CUDA 版 torch，传入 --device cuda（Apple Silicon 用 MPS）。
内存不足 / 极慢：逐个文件转换，降低 --num-threads，数字 PDF 加 --no-ocr。

Step 12

安装 FAQ

Docling 需要哪个 Python 版本？

Python 3.10 及以上，64 位。3.9 支持止于 2.70.0。若为 3.9 或 32 位，请新建 3.10–3.12 环境重装。

pip 还是 uv？

两者安装同一软件包。uv 解析预编译 Wheel 更积极，可避开 Windows 的 MSVC 编译器报错，且处处更快。用 uv：uv add docling，否则 pip install docling 足矣。

需要 Docker 吗？

本地转换不需要，Python 包足够。Docker（或 Podman）仅用于以容器运行 docling-serve（HTTP API 服务器）。见Docker 指南。

需要 GPU 吗？

不需要，一切可跑在 CPU 上。CUDA GPU（Linux/Windows）或 MPS（Apple Silicon）能显著加速长文档的版式、表格与 OCR。

为何首次转换这么慢？

Docling 首次使用下载模型。请保持该次连接，或以 docling-tools models download --all 预下载，之后复用缓存。

哪种 OCR 引擎最易安装？

RapidOCR（docling[rapidocr]）或 EasyOCR（docling[easyocr]），均为纯 pip。Tesseract 很强但需系统可执行文件加语言数据；OcrMac 仅 macOS。

可以离线安装 Docling 吗？

可以，需准备：在联网机器备好 Wheel 与模型缓存，一并转移。在离线主机将 DOCLING_CACHE_DIR 指向复制来的缓存。

如何配合 RAG 框架使用？

先装 Docling，再加框架适配器（LangChain、LlamaIndex、Haystack）。转 Markdown 或 JSON 后分块嵌入。见RAG 指南与示例。

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