ガイド

Doclingのインストール

ゼロから初変換までの完全検証済みルート。Python設定、pipとuv、仮想環境、全任意エクストラ、CPU/CUDA/MPS版PyTorch、Tesseract本体、モデル取得、検証とOS別対処。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。ContainerDockerHTTP 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	エクストラ表 + OCRガイド	RapidOCR・EasyOCR・Tesseract・OcrMacから選択。

Step 2

前提条件 (全プラットフォーム)

3.10未満なら先に新しいPythonを導入。以降はすべて3.10以降前提:

python --version && pip --version

Python 3.10以降・64bit。 Python 3.9はDocling 2.70.0でサポート終了。最新PythonでWheelが無い場合はPyPI履歴を確認。
pip 23以降かAstral uv。 uvは高速でWindowsのコンパイラ問題の大半を回避。
2〜4GB程度の空き (初回実行時のレイアウト・表・OCRモデル用)。
初回実行時は有効なネット接続 (モデル取得のため。オフライン機はモデルキャッシュ参照)。
任意: Tesseract本体 (Tesseract系のみ)、CUDAドライバ (NVIDIA GPUのみ)、Docker (docling-serveのみ)。

Step 3

分離環境を作る (推奨)

案A — venv + pip (どこでも): Windows PowerShellではsource行の代わりに.venv\Scripts\Activate.ps1を使う。

python -m venv .venv

source .venv/bin/activate

python -m pip install -U pip

DoclingはPyTorch・ONNX・OCRライブラリを連れてくる。システムPythonには絶対に入れない。torchやnumpy1つの競合で他ツールが壊れる。

案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

任意エクストラ全解説

基本パッケージは標準変換をカバー。重い外部依存はエクストラ化されている。pip install "docling[名前]" (カンマ結合可: "docling[rapidocr,vlm]")。

エクストラ	追加内容	導入
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で大半は足りるが、3ケースは専用ビルドが必要:

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専用サーバー: 巨大なCUDA版Wheelではなく小型CPUビルドを (下記コマンド)。
Linux/WindowsのNVIDIA GPU: 自分のCUDA版に合うtorchを入れ、--device cudaで選択。WindowsではWSL2が最短ルート。詳細は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系利用時のみ必要。本体をOSパッケージャで先に入れ、TESSDATA_PREFIXを言語データに向ける (末尾/必須):

OS	導入	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

導入を検証する

以下の3確認を順に。各々が別の失敗層を切り分ける。初回テストは小さなデジタル (テキスト) 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・ロックファイル・コンテナタグ)。下記バッジの版で本サイトは検証済み。

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)。3.9は2.70.0以降非対応。
OCRエクストラ失敗: rapidocrかeasyocr (pipのみ)。Tesseractは本体 + TESSDATA_PREFIXが先。
GPU無視 (CPU動作): torch.cuda.is_available()がTrueか確認しCUDA版torch導入、--device cuda指定 (Apple SiliconはMPS)。
メモリ不足・極遅: 1件ずつ変換、--num-threads低下、デジタルPDFは--no-ocr。

Step 12

導入FAQ

必要なPython版は?

Python 3.10以降・64bit。3.9対応は2.70.0で終了。3.9や32bitなら3.10〜3.12の新規環境で再導入。

pipとuvどちらで?

成果物は同一。uvはビルド済みWheel解決が積極的で、WindowsのMSVCエラーを回避し全体に高速。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-tools models download --allで事前取得。以後はキャッシュ利用。

最も導入が易しいOCRは?

RapidOCR (docling[rapidocr]) かEasyOCR (docling[easyocr])。共にpipのみ。Tesseractは高性能だが本体+言語データ要。OcrMacはmacOSのみ。

オフライン導入できる?

可。接続機でWheelとモデルキャッシュを用意し転送。隔離機ではDOCLING_CACHE_DIRをコピー先に向ける。

RAG基盤と使うには?

Docling導入後に対応アダプタ (LangChain・LlamaIndex・Haystack) を追加。Markdown/JSON化後にチャンク化・埋め込み。RAGガイド・事例集参照。

Docling v2.129.0で検証 · 最終確認 2026-09-22 · 公式ソース