安装

在 Linux 上安装 Docling

Ubuntu / Debian、RHEL / Fedora 与 WSL2 + Python 3.10 及以上。先定 CPU 还是 CUDA 路线，它决定安装哪个 PyTorch Wheel。每条命令请对照官方安装文档核对。

Step 1

前置要求 + 发行版软件包

需要 3.10+。再装 venv 与构建基础：

python3 --version

sudo apt-get update && sudo apt-get install -y python3 python3-venv python3-pip

RHEL / Fedora：

sudo dnf install -y python3 python3-pip

python3 -m venv .venv && source .venv/bin/activate && pip install -U pip

Step 2

纯 CPU 安装（服务器、容器）

默认 torch Wheel 捆绑 CUDA 库（2 GB+）。纯 CPU 机器请装小体积 CPU 构建。适合 CI、轻量 VPS 与 CPU Docker 镜像。文本 PDF 完全够用；扫描/OCR 重活只是比 GPU 慢。

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

Step 3

CUDA / GPU 安装（NVIDIA）

pip install docling

python -c "import torch; print(torch.cuda.is_available())"

docling convert report.pdf --device cuda

按 GPU 安装 NVIDIA 驱动 + CUDA toolkit（查 nvidia-smi）。
从 pytorch.org 按自身 CUDA（12.8 / 13.0）安装对应 torch 再装 Docling，或让 pip 从默认索引解析 CUDA 版 torch 再选设备：

torch.cuda.is_available() 须输出 True，否则先修驱动/torch 再调 Docling 参数。GPU OCR 追加 ONNX Runtime CUDA 路线：pip install "docling[onnxruntime]"，确认 CUDAExecutionProvider 出现在 ort.get_available_providers()。精调（批量、VLM 服务）见官方 GPU 指南。

Step 4

uv 的 CPU 索引配置

uv 用户在 pyproject.toml 把 torch 锁定到 CPU 索引，使每位成员与 CI 都拿到小 Wheel：

uv add docling

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

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

Step 5

Tesseract 系统包

仅 Tesseract 引擎需要。可执行文件须先于 pip extra 安装。将 TESSDATA_PREFIX 指向含 .traineddata 的目录（须以 / 结尾）。Debian 以 dpkg -L tesseract-ocr-eng | grep tessdata$ 定位，RHEL 用 /usr/share/tesseract/tessdata/。tesserocr 构建失败：pip uninstall tesserocr 后 pip install --no-binary :all: tesserocr。

Debian / Ubuntu：

sudo apt-get install -y tesseract-ocr tesseract-ocr-eng libtesseract-dev libleptonica-dev pkg-config

RHEL / Fedora，再装绑定：

sudo dnf install -y tesseract tesseract-devel tesseract-langpack-eng tesseract-osd leptonica-devel

pip install "docling[tesserocr]"

Step 6

Linux 的 OCR 与流水线 extra

需求	安装	限制
RapidOCR（推荐默认）	`pip install "docling[rapidocr]"`	无，纯 pip。
EasyOCR	`pip install "docling[easyocr]"`	无，纯 pip。
VLM 流水线	`pip install "docling[vlm]"`	强烈建议 GPU。
ASR（音频）	`pip install "docling[asr]"`	无。
Nemotron OCR	`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。

Step 7

验证（CPU 与 GPU）

首次运行下载模型，请保持连接或以 docling-tools models download --all 预下载。以 --device cpu 强制 CPU 对比，NVIDIA 用 --device cuda。

docling --help

docling convert sample.pdf --to md

docling convert sample.pdf --device auto --to md

Step 8

偏爱容器？用 docling-serve

若要 HTTP API 而非 CLI，运行官方容器（所示为 CPU 镜像），完整说明见Docker 页：

podman run -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=1 quay.io/docling-project/docling-serve-cpu

Step 9

常见 Linux 问题

GPU 被忽略——见GPU 未使用：torch 构建错误或缺驱动。
内存不足——见内存不足：逐个转换，降低 --num-threads，数字 PDF 加 --no-ocr。
安装体积巨大——在 CPU 机器拉了 CUDA 版 torch；改用 --extra-index-url …/cpu 行重装。
Tesseract 缺语言——安装 tesseract-ocr-语言 包并导出 TESSDATA_PREFIX。
权限错误——使用 venv；切勿 sudo pip install。

Step 10

Linux FAQ

CPU 还是 CUDA 版 torch？

纯 CPU 服务器与 CI：/whl/cpu 索引（小、下载快）。要速度的 NVIDIA 机器：CUDA 版 torch 加 --device cuda。

CUDA 用哪个版本？

与驱动 CUDA 对应（查 nvidia-smi）。docling-serve 发布 -cu128 与 -cu130 镜像；pip 安装按 pytorch.org 对该 CUDA 的推荐索引选择。

能用 Nemotron OCR 吗？

仅 Linux x86_64 + Python 3.12 + CUDA 13.x，以 feat-ocr-nemotron extra 加 cu130 索引与 unsafe-best-match 策略安装。

Tesseract 用 apt 还是 pip？

都要：可执行文件与开发库来自 apt/dnf，Python 绑定（tesserocr）来自 pip，之后设置 TESSDATA_PREFIX。

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