安装

在 Windows 上安装 Docling

Windows 10 / 11（64 位）+ Python 3.10 及以上。最短可靠路线是 64 位 Python + 虚拟环境 + uv。每条命令请对照官方安装文档核对。

Step 1

前置核对表

目标是 3.10+ 与 64。若看到 32，请卸载该 Python 并安装 64 位构建：

py --version; py -c "import struct; print(struct.calcsize('P')*8)"

Windows 10 或 11，64 位（32 位 Python 会在 torch Wheel 上失败）。
Python 3.10、3.11 或 3.12 的 64 位版，来自 python.org，首屏勾选「Add python.exe to PATH」。
PowerShell（或 Windows Terminal）。以下命令默认 PowerShell。
预留约 2–4 GB 空间供首次模型下载。

Step 2

正确安装 64 位 Python

py --version

pip --version

下载 Python 3.11 或 3.12 的 Windows 安装程序（64 位）。
首屏勾选 「Add python.exe to PATH」，再点「Install Now」。
在新建 PowerShell 窗口确认：

若找不到 py，请关闭重开终端（刷新 PATH）或勾选 PATH 重装。Microsoft Store 的 Python 垫片可能遮蔽 python，建议用 py 启动器或 python.org 构建。

Step 3

在 PowerShell 创建虚拟环境

若执行策略阻止激活，先执行一次 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 再激活。

py -m venv .venv

.venv\Scripts\Activate.ps1

python -m pip install -U pip

Step 4

最快安装：uv（推荐）

uv 解析预编译 Wheel，可避开 Windows 下大多数原生编译失败。附 extra 示例：

uv add docling

uv add "docling[rapidocr]"

已有 uv 项目则：uv venv --python 3.12 并激活，再 uv pip install docling。

Step 5

标准安装：pip

成功即完成，请跳到验证。若 pip 开始编译并报 C++ 错误，不必硬扛：切到上文 uv，或按下一节修复工具链。

pip install docling

Step 6

修复“Microsoft Visual C++ 14.0 is required”

原因：部分可选依赖含原生 C++ 扩展。缺少 MSVC 工具链时 pip 回退到源码构建而失败。方案 A（最易）——改用 uv拿 Wheel，无需编译器。方案 B——安装工具链：

winget install Microsoft.VisualStudio.2022.BuildTools

在安装程序勾选 「使用 C++ 的桌面开发」工作负载（MSVC 14.0+）。
重启终端、重新激活 venv，必要时删除半成品环境并重试 pip install docling。
核心 Docling 多有 Wheel，该报错多见于 tesserocr 或 fasttext 等 extra。若仅某 extra 需编译，可改用 rapidocr/easyocr。

Step 7

Windows 的 OCR extra

质量与语言对比见OCR 指南。扫描版 PDF 请强制整页 OCR：docling convert scan.pdf --ocr-mode full_page。

引擎	Windows 安装	说明
RapidOCR（最省事）	`pip install "docling[rapidocr]"`	仅 pip，无系统可执行文件。Windows 默认之选。
EasyOCR	`pip install "docling[easyocr]"`	仅 pip，下载较大，多语言好。
Tesseract	装 UB Mannheim 可执行文件并设 PATH 与 `TESSDATA_PREFIX`，再 `pip install "docling[tesserocr]"`	精度可控性最佳，但需系统可执行文件加语言数据。

Step 8

经 WSL2 使用 GPU / CUDA

Windows 原生 CUDA 取决于 PyTorch 构建与驱动。最可靠的 GPU 路线是 WSL2 + Ubuntu + WSL 版 NVIDIA CUDA 驱动：

docling convert report.pdf --device cuda

从 Microsoft Store 安装 WSL2 + Ubuntu，并安装支持 WSL 的 NVIDIA Windows 驱动。
在 WSL2 内按Linux 指南操作（CUDA 版 torch），再显式指定设备：

以 python -c "import torch; print(torch.cuda.is_available())" 确认输出 True，否则 GPU 参数无从谈起。纯 CPU 安装完全可用，GPU 只提速。

Step 9

验证

先用小型数字 PDF（无 OCR、无 GPU）。首次运行下载模型，请保持连接。之后尝试 --to json 与某 OCR 引擎，逐层确认。

docling --help

docling convert sample.pdf --to md

Step 10

常见 Windows 错误

安装失败 / 要求 C++ 14.0——见安装失败与要求 MSVC 14.0。
python 打开 Microsoft Store——改用 py 启动器或关闭 Store 别名，建议 python.org 构建。
32 位 torch Wheel /「not a supported wheel」——装了 32 位 Python，请重装 64 位。
权限错误——勿以管理员 shell 蒙混；venv 加不带 --user 的安装才是正解。
首次转换慢——正常（正在下载模型）。可以 docling-tools models download --all 预下载。

Step 11

Windows FAQ

Windows 下 uv 还是 pip？

建议 uv add docling。它解析预编译 Wheel，可绕开 pip 在可选 extra 上要求的 MSVC 工具链。

需要 Visual Studio 吗？

仅当 pip 试图编译原生 extra 时需要。核心包多半直装。若报 C++ 14.0 错误，以 winget 安装 Build Tools 2022（含 C++ 工作负载）或切到 uv。

Windows 下哪种 OCR 引擎最省事？

RapidOCR 或 EasyOCR，均为纯 pip。Tesseract 需 UB Mannheim 系统可执行文件加 TESSDATA_PREFIX。

Windows 下能用 NVIDIA GPU 吗？

可以。若 torch 构建支持则原生 CUDA 可行，否则 WSL2 + Ubuntu + CUDA 驱动最可靠，再加 --device cuda。

PowerShell 阻止 venv 激活？

执行一次 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser，再运行 .venv\Scripts\Activate.ps1。

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