Docling 安装与下载教程（2026）：pip、uv、仅 CPU、GPU 与离线部署

Q: 安装 Docling 的命令是什么？

在 Python 3.10–3.14 的虚拟环境中运行 pip install docling。使用 uv 时，在 uv 项目中运行 uv add docling，或在虚拟环境中运行 uv pip install docling。用 docling --version 验证安装。

Q: Docling 安装后有多大？

在我们的 Linux 测试中，包含 docling 和 CPU 版 PyTorch 的全新虚拟环境占用 1.8 GB 磁盘，首次运行时默认模型又增加 0.5 GB。在 Linux 上使用 PyPI 默认的 PyTorch 会额外下载约 3 GB 的 CUDA 库。

Q: docling 和 docling-slim 有什么区别？

自 2026 年 4 月起代码发布在 docling-slim 中，它默认只安装核心数据模型，其余功能以可选组件提供。docling 包是一个封装，会安装 docling-slim[standard]——包括 CLI、PDF 与 Office 后端、版面与表格模型、RapidOCR 和分块功能。在我们对 docling 2.148.0 的测试中，CLI 和所有 PDF 转换都需要 PyTorch；自 2.144.0 起，Python API 可以用 docling-slim[format-docx,format-pptx,convert-core] 这类不含 PyTorch 的精简安装转换 Office 文件。当转换由 docling-serve 服务器完成时，docling-slim[service-client] 是轻量的选择。

Q: 没有网络能安装 Docling 吗（本地部署）？

可以，但需要先在能联网的机器上准备：用 pip download 下载安装包，用 docling-tools models download 下载模型，拷贝到目标机器后从本地目录安装，并通过 --artifacts-path 或 DOCLING_ARTIFACTS_PATH 指向模型目录。

Q: 如何升级 Docling？

运行 pip install -U docling（或 uv pip install -U docling），再用 docling --version 确认。Docling 更新频繁，生产环境请固定版本（例如 docling==2.148.0），有计划地升级。

选择你的安装命令#

选择操作系统、安装工具、硬件和需要的功能，命令会实时更新——与我们在干净机器上运行的命令完全一致。

环境要求一览#

项目	Docling 2.148.0	依据
Python	3.10、3.11、3.12、3.13、3.14（`>=3.10,<4.0`）	PyPI 的 `requires_python` 与分类信息
操作系统	macOS、Linux、Windows	PyPI 分类信息、README
CPU 架构	x86_64 与 arm64	README
加速设备	CPU、NVIDIA CUDA、Apple MPS、Intel XPU	`--device` 可选值：auto、cpu、cuda、mps、xpu
磁盘	约 1.8 GB 环境 + 约 0.5 GB 模型（CPU 版 PyTorch）	我们用 `du -sh` 实测
Python 3.9	自 2.70.0 起不再支持	README

使用 pip 分步安装#

创建虚拟环境

bash

python3 -m venv .venv
source .venv/bin/activate        # Windows：.venv\Scripts\activate
python -m pip install -U pip

没有 GPU 的 Linux？先安装仅 CPU 的 PyTorch
Linux 上 PyPI 默认的 PyTorch 依赖 NVIDIA CUDA 库。先从 PyTorch 的 CPU 源安装，之后 pip 就不会再下载它们。
bash
```
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
```

安装 Docling

bash

pip install docling
# 国内网络可使用清华镜像：
pip install docling -i https://pypi.tuna.tsinghua.edu.cn/simple
# 生产环境建议固定版本：
pip install "docling==2.148.0"

验证

bash

docling --version

我们机器上的输出

Docling version: 2.148.0
Docling Core version: 2.106.0
Docling IBM Models version: 4.0.4
Docling Parse version: 7.24.2
Python: cpython-313 (3.13.18)
Platform: Linux-6.18.44-fc-v242-x86_64-with-glibc2.39

第一次转换
bash
```
docling convert https://arxiv.org/pdf/2408.09869 --to md --no-ocr
```
首次运行会从 Hugging Face 下载版面模型（docling-project/docling-layout-heron）和 TableFormer（docling-project/docling-models）——在我们的缓存中共 506 MB。如果无法访问 Hugging Face，可设置 HF_ENDPOINT 使用镜像，或参考下文的离线安装。

为什么要先装 CPU 版#

我们读取了 PyTorch 2.15.0 在 Linux x86_64、Python 3.13 下需要下载的安装包大小。默认版本会带上 cuDNN、cuBLAS、NCCL、Triton 以及 CUDA 工具包的其余部分——即使服务器上根本没有 GPU。

Linux 上 PyTorch 的下载大小Linux x86_64、Python 3.13 下 torch 2.15.0 需要下载的压缩包总量。Docling 的版面、表格和 OCR 模型依赖 PyTorch。

docling.org 于 2026 年 11 月 6 日读取 PyPI 与 download.pytorch.org 的文件元数据。

查看数据表

Linux 上 PyTorch 的下载大小
	GB
CPU 版（download.pytorch.org/whl/cpu）	0.21 GB
PyPI 默认版（含 CUDA 13 依赖）	2.98 GB

我们实测的磁盘占用Linux、Python 3.13、Docling 2.148.0、PyTorch 2.15.0 全新虚拟环境（pip）的安装体积。

docling.org 于 2026 年 11 月 6 日用 du 测量。

查看数据表

我们实测的磁盘占用
	GB
仅 docling-slim（无 extras）	0.25 GB
pip install docling + CPU 版 PyTorch	1.79 GB
默认模型（首次运行下载）	0.51 GB

使用 uv 安装#

uv 解析依赖比 pip 快得多，还能通过 --torch-backend 替你选择 PyTorch 版本。我们用 uv 0.11.32 确认 --torch-backend cpu 会解析到 torch==2.15.0+cpu。

bash在 uv 项目中

uv init my-app && cd my-app
uv add docling
uv run docling --version

bash在普通虚拟环境中

uv venv --python 3.12
source .venv/bin/activate
uv pip install --torch-backend cpu docling     # 仅 CPU 的 PyTorch
# uv pip install --torch-backend auto docling  # 让 uv 自动检测 CUDA 驱动

docling 与 docling-slim#

自 2026 年 4 月 29 日起，代码发布在 docling-slim 中，它默认只安装核心数据模型，功能按需选装。docling 现在是一个封装包，会安装 docling-slim[standard]。

安装方式	包含内容	适用场景
`pip install docling`	CLI、PDF（docling-parse、pypdfium2）、Word、PowerPoint、Excel、HTML、Markdown、邮件、版面 + TableFormer 模型、RapidOCR、分块、PyTorch	在本机转换文档
`pip install "docling-slim[service-client]"`	`docling convert-remote` 命令和 DoclingDocument 数据模型——在我们的测试中环境仅 258 MB，不含 PyTorch	转换由 docling-serve 服务器完成
`pip install docling-slim`	仅 docling-core 与数据模型	只需加载、查看或序列化 DoclingDocument JSON

可选组件（extras）#

以下是 2.148.0 中 docling 包声明的全部可选组件，以及各自增加的依赖。

组件	新增依赖	用途
`docling[vlm]`	transformers、accelerate、timm、peft、qwen-vl-utils、open-clip-torch；Apple Silicon 上还有 mlx-vlm	VLM 流水线（Granite-Docling 等预设）、图片描述
`docling[asr]`	openai-whisper、whisper-s2t-reborn、numba；Apple Silicon 上还有 mlx-whisper	音频转写（还需要 FFmpeg）
`docling[easyocr]`	easyocr、scikit-image	EasyOCR 引擎
`docling[tesserocr]`	tesserocr、pandas	通过 C API 调用 Tesseract（需系统已装 Tesseract）
`docling[rapidocr]`	rapidocr、onnxruntime	使用默认 onnxruntime 后端的 RapidOCR
`docling[onnxruntime]`	onnxruntime（可用时为 onnxruntime-gpu）	基于 ONNX 的模型
`docling[ocrmac]`	ocrmac	macOS 上的 Apple Vision OCR
`docling[htmlrender]`	playwright	转换前渲染 HTML 页面
`docling[xbrl]`	arelle-release	XBRL 财务报告
`docling[remote-serving]`	tritonclient[grpc]	远程模型服务（KServe v2 / Triton）

视频文件需要 docling-slim[format-video]，它没有作为 docling 的组件提供。多个组件可一次安装：pip install "docling[vlm,easyocr]"。

GPU 与 Apple Silicon#

NVIDIA（Linux、Windows）：运行 nvidia-smi 查看其显示的 CUDA 版本——这是驱动支持的最高 CUDA 版本。从匹配的源安装 PyTorch（torch 2.15.0 发布在 cu132 和 cu134 源上；cu130 和 cu126 只到 2.14.1，Docling 同样可用），然后再安装 Docling。用 python -c "import torch; print(torch.cuda.is_available())" 检查。
Apple Silicon：普通安装已包含 MPS 支持。Docling 会自动选择设备，也可用 --device mps 强制使用。
Intel GPU：支持 --device xpu，需要带 XPU 支持的 PyTorch。

GPU 能带来哪些变化，请看性能指南。

离线与内网环境（本地部署）#

Docling 首次使用时会从 Hugging Face 下载模型。若要在无网络的环境中运行，请先在能联网的机器上准备：

bash在可联网的机器上

pip download "docling==2.148.0" -d wheels/
docling-tools models download -o models/
# 默认下载：版面、TableFormer、代码/公式、图片分类、RapidOCR
# 按名称追加，例如：docling-tools models download granitedocling easyocr -o models/

bash在离线机器上

pip install --no-index --find-links wheels/ docling
export DOCLING_ARTIFACTS_PATH=/path/to/models
docling convert report.pdf --to md
# 或按命令指定：docling convert report.pdf --artifacts-path /path/to/models

不加 -o 时，docling-tools models download 会写入 ~/.cache/docling/models。DOCLING_ARTIFACTS_PATH 由 Docling 的配置读取，在未显式传入路径时对所有流水线生效。

升级与锁定版本#

Docling 在 2024 年 7 月到 2026 年 11 月之间发布了 238 个版本，参数确实会变化：在 2.148.0 中 --force-ocr 和 --psm 已被弃用，分别由 --ocr-mode full_page 和 --ocr-option psm=N 取代。生产环境请锁定版本，有计划地升级：

bash

pip install -U docling
docling --version
pip freeze | grep -i docling     # 记录确切版本

按平台继续#

Windows

python.org 的 Python、PATH 问题、PowerShell 激活与 CUDA。

Windows 指南 →

macOS

Apple Silicon、MPS 加速和系统自带的 Vision OCR 引擎。

macOS 指南 →

Linux

系统依赖、无界面服务器、仅 CPU 环境与 CUDA。

Linux 指南 →

Docker

官方 docling-serve 镜像、大小与 GPU 版本。

Docker 指南 →

常见问题

安装 Docling 的命令是什么？

在 Python 3.10–3.14 的虚拟环境中运行 pip install docling。使用 uv 时，在 uv 项目中运行 uv add docling，或在虚拟环境中运行 uv pip install docling。用 docling --version 验证安装。

Docling 安装后有多大？

在我们的 Linux 测试中，包含 docling 和 CPU 版 PyTorch 的全新虚拟环境占用 1.8 GB 磁盘，首次运行时默认模型又增加 0.5 GB。在 Linux 上使用 PyPI 默认的 PyTorch 会额外下载约 3 GB 的 CUDA 库。

docling 和 docling-slim 有什么区别？

自 2026 年 4 月起代码发布在 docling-slim 中，它默认只安装核心数据模型，其余功能以可选组件提供。docling 包是一个封装，会安装 docling-slim[standard]——包括 CLI、PDF 与 Office 后端、版面与表格模型、RapidOCR 和分块功能。在我们对 docling 2.148.0 的测试中，CLI 和所有 PDF 转换都需要 PyTorch；自 2.144.0 起，Python API 可以用 docling-slim[format-docx,format-pptx,convert-core] 这类不含 PyTorch 的精简安装转换 Office 文件。当转换由 docling-serve 服务器完成时，docling-slim[service-client] 是轻量的选择。

没有网络能安装 Docling 吗（本地部署）？

可以，但需要先在能联网的机器上准备：用 pip download 下载安装包，用 docling-tools models download 下载模型，拷贝到目标机器后从本地目录安装，并通过 --artifacts-path 或 DOCLING_ARTIFACTS_PATH 指向模型目录。

如何升级 Docling？

运行 pip install -U docling（或 uv pip install -U docling），再用 docling --version 确认。Docling 更新频繁，生产环境请固定版本（例如 docling==2.148.0），有计划地升级。

资料来源

内容准确吗？当 Docling 新版本改变行为时，我们会重新验证页面。如果某条命令对你无效，请把 Docling 版本号和报错发到 hello@docling.org，更正通常一天内上线。

正确安装 Docling——更小、更快、可离线

选择你的安装命令#

环境要求一览#

使用 pip 分步安装#

为什么要先装 CPU 版#

使用 uv 安装#

docling 与 docling-slim#

可选组件（extras）#

GPU 与 Apple Silicon#

离线与内网环境（本地部署）#

升级与锁定版本#

按平台继续#

Windows

macOS

Linux

Docker

常见问题

资料来源

继续阅读

Windows

macOS

Linux

Docker

故障排查

配置生成器