Docling 安装完全指南：pip/uv 安装、PyTorch 变体选择、Extras 依赖体系与 OCR 引擎配置

本文基于 Docling 官方安装文档（installation.md）整理并深度扩充，覆盖从 pip/uv 基础安装到 PyTorch 发行版选择、macOS Intel 兼容方案、extras 可选依赖体系、七大 OCR 引擎的系统级安装配置，以及本地开发环境搭建的完整路径。读完本文，你可以为不同操作系统、架构与加速硬件（CPU/CUDA/MLX）规划出可复现的 Docling 安装方案，并理解 extras 声明背后的实际依赖结构。

基础安装

使用 Docling 的第一步是从 Python 包管理器安装 docling 包。

pip 用户：

pip install docling

uv 用户：

uv add docling

Docling 支持 macOS、Linux 和 Windows 三大平台，覆盖 x86_64 与 arm64 两种架构。从当前仓库的 pyproject.toml 可以看到，Python 版本要求为 >=3.10,<4.0，项目声明的分类器覆盖 Python 3.10 至 3.14，因此安装前请确认解释器版本在 3.10 及以上。

理解 docling 与 docling-slim 的包结构

安装命令虽然只是 pip install docling，但从仓库源码看，docling 实际上是一个元包（meta-package）。packages/docling/pyproject.toml 中明确写着：

# Meta-package: pulls in docling-slim with standard extras (includes CLI).
# The `docling` Python module itself is provided by docling-slim.
dependencies = [
  'docling-slim[standard]==2.124.0',
]

也就是说：

• 所有实际的 Python 代码（docling/ 模块）都打包在 docling-slim 的 wheel 中；
• docling wheel 本身不携带任何源码（bypass-selection = true），仅作为依赖声明的入口，这一设计避免了两个 wheel 同时提供同名 docling/ 模块导致的安装冲突（源码注释中明确提到了此前该 bug 的修复）；
• docling 包默认拉取 docling-slim[standard]，包含 PDF、Office、Web、LaTeX、Email、iWork 等格式的解析依赖、本地模型（models-local）、RapidOCR、chunking、服务客户端与 CLI 工具，是一套开箱即用的标准组合。

CLI 入口点 docling 与 docling-tools（对应 docling/cli/main.py 和 docling/cli/tools.py）也在 packages/docling/pyproject.toml 中重新声明，以便 uv tool install docling 能正确将可执行文件链接到 ~/.local/bin。

选择 PyTorch 发行版

Docling 的模型依赖 PyTorch 库。根据目标架构，你可能需要使用不同的 torch 发行版，例如针对特定加速器的版本，或者 CPU-only 版本。所有 torch 安装方式的官方清单以 PyTorch 官网为准（Docling 文档未在此列举具体 URL，此处仅引用文档原文的说明）。

Linux CPU-only 场景

在仅有 CPU 的 Linux 系统上安装 Docling，是替代发行版中最常见的情况。Docling 文档建议：

# Example for installing on the Linux cpu-only version
pip install docling --extra-index-url https://download.pytorch.org/whl/cpu

通过 --extra-index-url 将 PyTorch 官方 CPU wheel 索引加入解析范围，pip 会优先解析到 CPU 版 torch，避免拉入庞大的 CUDA 依赖。

对于 uv 用户，等价做法是把 PyTorch CPU 索引声明进项目的 pyproject.toml：

[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

然后将 torch 固定到该索引：

[tool.uv.sources]
torch = [{ index = "pytorch-cpu" }]

之后再执行：

uv add docling

explicit = true 的含义是该索引只对显式 pin 到它的包（即 torch）生效，不会污染其他包的解析。

macOS Intel（x86_64）安装

在 Intel 处理器的 Mac 上安装 Docling 时，可能会遇到 PyTorch 兼容性错误。原因是较新的 PyTorch 版本（2.6.0+）不再为 Intel Mac 提供 wheel。若你在 Intel Mac 上开发，需要安装与旧版 PyTorch 兼容的依赖组合：

注意：PyTorch 2.2.2 要求 Python 3.12 或更低版本，请确认你没有使用 Python 3.13+。

# For uv users
uv add torch==2.2.2 torchvision==0.17.2 docling

# For pip users
pip install "docling[mac_intel]"

# For Poetry users
poetry add docling

从源码结构看，这个 pin 与依赖声明是自洽的：pyproject.toml 中 models-local extra 的 torch 约束为 >=2.2.2,<3.0.0，因此 Intel Mac 上固定 torch==2.2.2 / torchvision==0.17.2 正好落在允许区间下界。另外需要说明的是，当前 packages/docling/pyproject.toml 中实际声明的 extras 重新导出映射为 easyocr、tesserocr、ocrmac、vlm、rapidocr、asr、htmlrender、remote-serving、onnxruntime、xbrl；文档中的 docling[mac_intel] 是面向 Intel Mac 的便捷入口，其中最稳妥、可验证的做法仍是 uv 那条命令——显式 pin 住 torch==2.2.2 与 torchvision==0.17.2 后再引入 docling。

Extras 可选依赖体系

docling 包的设计目标是：为 Docling 的默认选项提供一套开箱即用的工作解。部分功能需要额外的第三方包，因此只有被选为 extras（或独立安装）时才会引入。extras 的启用方式是：

pip install "docling[NAME1,NAME2]"

官方文档列出的 extras 汇总如下：

Extra	说明
asr	安装运行 ASR 流水线所需的依赖。
vlm	安装运行 VLM 流水线所需的依赖。
easyocr	安装 EasyOCR OCR 引擎。
feat-ocr-nemotron	安装 NVIDIA Nemotron OCR。仅支持 Linux x86_64、Python 3.12 与 CUDA 13.x。
tesserocr	安装 Tesseract 绑定包，用于将 Tesseract 作为 OCR 引擎。
ocrmac	安装 OcrMac OCR 引擎。
htmlrender	安装 HTML 后端中渲染 HTML 页面所需的依赖。
rapidocr	安装基于 onnxruntime 后端的 RapidOCR OCR 引擎。

Extras 在源码中的实际映射

这些文档层 extras 在 packages/docling/pyproject.toml 中被“重新导出”为底层 docling-slim 的对应 extra，保持了向后兼容的命名：

[project.optional-dependencies]
easyocr = ['docling-slim[feat-ocr-easyocr]==2.124.0']
tesserocr = ['docling-slim[feat-ocr-tesserocr]==2.124.0']
ocrmac = ['docling-slim[feat-ocr-mac]==2.124.0']
vlm = ['docling-slim[models-vlm-inline]==2.124.0']
rapidocr = ['docling-slim[feat-ocr-rapidocr-onnx]==2.124.0']
asr = ['docling-slim[format-audio]==2.124.0']
htmlrender = ['docling-slim[format-html-render]==2.124.0']
remote-serving = ['docling-slim[models-remote]==2.124.0']
onnxruntime = ['docling-slim[models-onnxruntime]==2.124.0']
xbrl = ['docling-slim[format-xml-xbrl]==2.124.0']

也就是说，vlm 实际引入的是 transformers、accelerate、peft 以及 Apple Silicon 上的 mlx-vlm 等内联 VLM 依赖；rapidocr 引入的是带 onnxruntime 后端的完整组合（feat-ocr-rapidocr-onnx）；asr 引入的是 format-audio（Whisper 家族 + mlx-whisper on Apple Silicon arm64）。

在 pyproject.toml 的 docling-slim 定义中，这些 extra 被组织为几大类：

• 格式支持：format-pdf、format-office（docx/pptx/xlsx）、format-web（html/markdown）、format-latex、format-email、format-iwork、format-xml-jats/uspto/xbrl、format-audio、format-video、format-html-render 等；
• OCR 引擎：feat-ocr-rapidocr、feat-ocr-rapidocr-onnx、feat-ocr-easyocr、feat-ocr-tesserocr、feat-ocr-mac、feat-ocr-nemotron；
• 模型：models-local（torch + docling-ibm-models + accelerate）、models-remote（tritonclient gRPC）、models-onnxruntime、models-vlm-inline；
• 便捷组合：standard（默认安装的标准捆绑）与 all（几乎包含全部能力的超集）。

值得注意的两个源码细节：

1. feat-ocr-nemotron 使用了条件依赖标记，仅在 python_version == "3.12" and sys_platform == "linux" and platform_machine == "x86_64" 时才安装 nemotron-ocr>=2.0.0——这就是文档中“仅支持 Linux x86_64 + Python 3.12 + CUDA 13.x”限制在包元数据层面的直接体现。
2. all 组合有意排除了 format-video，注释说明 resemblyzer 依赖 webrtcvad，后者没有预编译 wheel、需要 Python 开发头文件与 C 编译器，而 all 必须保证无需编译器即可干净安装，因此说话人分离（speaker diarization）保持通过 docling-slim[format-video] 显式选装。

仓库中的 tests/test_backend_optional_dependencies.py 还固化了“可选依赖缺失时保持惰性”这一契约：即使缺少 bs4、marko、docx 等第三方包，DocumentConverter 依然可以被构造；只有真正使用对应后端时才会抛出携带安装提示（extra 名称）的 ImportError。这保证了按需选装 extras 的 slim 安装不会因缺包而彻底不可用。

OCR 引擎选择

Docling 支持多种 OCR 引擎处理扫描件，当前版本提供的引擎及安装方式如下（原文档表格）：

引擎	安装方式	使用（Options 类）
EasyOCR	easyocr extra，或 pip install easyocr。	EasyOcrOptions
Nemotron OCR	feat-ocr-nemotron extra。仅支持 Linux x86_64 + Python 3.12 + CUDA 13.x，安装注意见下文。	NemotronOcrOptions
Tesseract	系统依赖，见下文 Tesseract 与 Tesserocr 说明。	TesseractOcrOptions
Tesseract CLI	系统依赖，见下文说明。	TesseractCliOcrOptions
OcrMac	系统依赖，见下文说明。	OcrMacOptions
RapidOCR	rapidocr extra，或 pip install rapidocr onnxruntime	RapidOcrOptions
OnnxTR	通过插件系统安装：pip install "docling-ocr-onnxtr[cpu]"（需参考其项目文档）。	OnnxtrOcrOptions

通过 ocr_options 指定引擎

DocumentConverter 允许通过 ocr_options 设置选择 OCR 引擎，官方示例：

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import (
    TesseractOcrOptions,
    PdfPipelineOptions,
)
from docling.document_converter import DocumentConverter, PdfFormatOption

pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.ocr_options = TesseractOcrOptions()  # Use Tesseract

doc_converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)}
)

上述所有 Options 类都定义在 docling/datamodel/pipeline_options.py 中，共同继承 OcrOptions 基类。基类提供三个与具体引擎无关的关键参数，理解它们有助于安装后正确调优：

• mode（OcrMode）：决定把哪些区域送入 OCR，可选 FULL_PAGE（整页 OCR）、LAYOUT_REGIONS、PDF_AWARE_LAYOUT_REGIONS、DEFAULT。旧的 force_full_page_ocr 布尔参数已废弃，等价的现代写法是 mode=OcrMode.FULL_PAGE；
• lang：OCR 语言列表，取值格式须与所选引擎的约定一致（例如 ["deu", "eng"]）；
• scale：OCR 前的图像缩放倍数，页面按 72 DPI 乘以该系数渲染，默认 3.0 即 216 DPI。若源图本身分辨率已很高，降低该值可避免过度放大反而劣化识别。

另外还有一个 OcrAutoOptions（kind = "auto"）：它在流水线初始化时探测运行时环境并自动挑选最佳可用引擎（例如存在 GPU 时倾向 EasyOCR，否则用 Tesseract），语言配置交给所选引擎的默认值——因此若需精确控制语言，应显式指定具体引擎的 Options 类。

系统依赖安装

Tesseract 安装与 Tesserocr 链接

Tesseract 是大多数操作系统上都可用的人气 OCR 引擎。要将 Tesseract 用于 Docling，必须先通过你所选的包管理器在系统层安装它。安装之后，需要通过 TESSDATA_PREFIX 环境变量提供其语言文件的路径（注意该值必须以斜杠 / 结尾）。

各发行版示例命令：

macOS（via Homebrew）：

brew install tesseract leptonica pkg-config
TESSDATA_PREFIX=/opt/homebrew/share/tessdata/
echo "Set TESSDATA_PREFIX=${TESSDATA_PREFIX}"

Debian-based：

apt-get install tesseract-ocr tesseract-ocr-eng libtesseract-dev libleptonica-dev pkg-config
TESSDATA_PREFIX=$(dpkg -L tesseract-ocr-eng | grep tessdata$)
echo "Set TESSDATA_PREFIX=${TESSDATA_PREFIX}"

RHEL：

dnf install tesseract tesseract-devel tesseract-langpack-eng tesseract-osd leptonica-devel
TESSDATA_PREFIX=/usr/share/tesseract/tessdata/
echo "Set TESSDATA_PREFIX=${TESSDATA_PREFIX}"

链接方式：使用 Tesseract 库最高效的方式是通过动态链接，Docling 使用 Tesserocr 包实现这一路径（对应 tesserocr extra，底层依赖 tesserocr>=2.7.1 及 pandas，见 pyproject.toml 的 feat-ocr-tesserocr 定义）。

如果 Tesserocr 安装遇到问题，文档建议的补救步骤是：

pip uninstall tesserocr
pip install --no-binary :all: tesserocr

--no-binary :all: 强制从源码编译 Tesserocr，从而让它正确链接到你系统里刚装好的 Tesseract 开发库（这就是为什么上面各系统的包管理器命令里都包含了 -devel/-dev 与 pkg-config）。

Nemotron OCR 安装

Nemotron OCR 需要 CUDA 13 的 PyTorch wheels。安装时须同时提供 feat-ocr-nemotron extra、CUDA 13 的 PyTorch 索引，以及 unsafe-best-match 索引策略，这样 pip 才能正确解析到带 CUDA 的 torch 包：

pip install "docling[feat-ocr-nemotron]" \
  --extra-index-url https://download.pytorch.org/whl/cu130 \
  --index-strategy unsafe-best-match

再次强调其支持边界：当前仅支持 Linux x86_64 + Python 3.12 + CUDA 13.x。这一点在源码中由条件依赖标记固化（feat-ocr-nemotron 只在 python_version == "3.12" 且平台为 linux x86_64 时才安装 nemotron-ocr>=2.0.0），在其他环境上即使执行了安装命令也不会实际引入该包。

开发环境搭建

若要在本地克隆仓库基础上开发 Docling 的功能、修复缺陷等，从仓库根目录执行：

uv sync --all-extras --no-extra feat-ocr-nemotron

feat-ocr-nemotron extra 被有意排除在默认开发环境之外，因为它仅能在 Linux x86_64 + Python 3.12 + CUDA 13.x 上使用——在多数开发机上强行解析该依赖会直接失败或引入不匹配 CUDA 版本的 torch。

仓库的 Makefile 还提供了面向 CI 风格工作流的 setup 目标，作为交叉验证：

setup: ## Install CI-style development environment.
	uv sync --frozen --group dev --all-extras --no-group docs --no-group examples

它额外显式激活 dev 依赖组（pytest、ruff、ty、tach 等开发工具，见 pyproject.toml 的 [dependency-groups]），并通过 --no-group 关闭文档构建与示例运行所需的 docs、examples 组，避免无关依赖膨胀。安装完成后可以用 make test 运行默认测试套件，用 make check 跑只读检查（格式化、lint、类型检查、模块边界检查等）。

小结与后续阅读

本文覆盖了 Docling 安装的完整决策链：

1. 常规安装：pip install docling 或 uv add docling，获得 docling-slim[standard] 标准捆绑与 CLI；
2. PyTorch 变体：CPU-only Linux 用 --extra-index-url（pip）或 [[tool.uv.index]] + [tool.uv.sources]（uv）；Intel Mac 固定 torch==2.2.2（Python ≤3.12）；
3. 按需选装 extras：asr、vlm、各 OCR 引擎、htmlrender 等，底层分别映射到 docling-slim 的 format-*/feat-ocr-*/models-* 声明；
4. 系统级依赖：Tesseract 系需系统安装 + TESSDATA_PREFIX（以 / 结尾）+ 可选 Tesserocr 源码编译链接；Nemotron OCR 锁定 Linux x86_64/Py3.12/CUDA 13；
5. 开发环境：uv sync --all-extras --no-extra feat-ocr-nemotron，与 Makefile 的 setup 目标互为补充。

安装完成后，可继续阅读 quickstart.md 了解 DocumentConverter 的基本用法与 CLI 调用，或通过 docling --help 与 CLI 参考页面探索全部命令行选项。