はじめに
RAG環境の構築をしている中でPDFをテキストファイルに落とす必要がでてきました。
PDFをテキストに変換する方法はいくつかありますが、今回はその中でもdoclingとするツールについて紹介したいと思います。
WSL Ubuntu 環境に docling をインストールして、PDF をテキストに変換するまでの手順を残しておきます。
対象者
- PDF や Word をプログラムからテキスト変換したい人
- RAG のデータ前処理としてドキュメント変換を試したい人
- WSL Ubuntu 環境で Python を使っている人
環境
- WSL2 Ubuntu
- Python 3.10 以上（docling の動作要件。3.8 では
No matching distributionエラーになる） - GPU なし（CPU 推論のみ）
- ディスク空き容量: 6GB 以上推奨
docling とは
docling は IBM Research が開発したオープンソースのドキュメント変換ライブラリです。PDF・Word・HTML・画像などの入力を、構造化された Markdown や JSON に変換できます。
| できること | 説明 |
|---|---|
| PDF 変換 | レイアウト解析・表抽出・OCR 付きで Markdown/JSON に変換 |
| 複数形式対応 | PDF・DOCX・PPTX・HTML・画像など |
| RAG 連携 | LlamaIndex・LangChain 向けのチャンク分割に対応 |
| CLI / Python API | コマンドラインでもスクリプトからでも使える |
全体の流れ
- Step 1: venv の作成
- Step 2: docling のインストール
- Step 3: 動作確認
Step 1: venv の作成
つまずきポイント 1: Python 3.10 以上が必要
docling は Python 3.10〜3.13 をサポートしています。Ubuntu のシステム Python が 3.8 や 3.9 の場合、pip install docling で以下のエラーになります。
ERROR: No matching distribution found for docling
pyenv や miniconda で 3.10 以上をインストールしてから venv を作成してください。
つまずきポイント 2: システム Python に直接インストールしない
システム Python に直接インストールすると、OS のツールが依存するパッケージと競合するリスクがあります。また Ubuntu 23.04 以降では PEP 668 により直接インストール自体がエラーになります。
error: externally-managed-environment
docling は依存が大きいため、venv で隔離してインストールするのが安全です。
# venv を作成
mkdir -p "$HOME/venvs"
python3 -m venv "$HOME/venvs/docling"
Step 2: docling のインストール
pip を更新してから docling をインストールします。
# pip を更新
"$HOME/venvs/docling/bin/python" -m pip install --upgrade pip
# docling をインストール
"$HOME/venvs/docling/bin/pip" install docling
インストール先: ~/venvs/docling
つまずきポイント 3: インストールに時間がかかる・容量が大きい
docling は PyTorch や CUDA 関連ライブラリ（nvidia-*）を依存に含むため、約 5.5GB のディスク容量を消費します。GPU がなくても CPU で動作しますが、インストール時間とディスク残量に注意してください。
Step 3: 動作確認
インポートの確認
"$HOME/venvs/docling/bin/python" -c "from docling.document_converter import DocumentConverter; print('import OK')"
import OK と表示されればインストール成功です。
PDF を Markdown に変換してみる
venv を有効化して docling コマンドで変換できます。
source ~/venvs/docling/bin/activate
docling sample.pdf
deactivate
カレントディレクトリに Markdown ファイルが出力されます。
つまずきポイント 4: 初回変換時にモデルが自動ダウンロードされる
初回の PDF 変換時に、レイアウト解析・OCR 用のモデルが Hugging Face から自動ダウンロードされます。初回だけ追加の待ち時間とディスク消費が発生します。
オフライン環境で使う場合は、事前にモデルを取得しておく必要があります。
使い方
source ~/venvs/docling/bin/activate
python your_script.py
deactivate
注意点
| # | ポイント | 詳細 |
|---|---|---|
| 1 | Python 3.10 以上が必要 | 3.8 や 3.9 では No matching distribution エラーになる。pyenv や miniconda で対応バージョンを用意する |
| 2 | システム Python に入れない |
--break-system-packages での強制インストールは OS のツールを壊すリスクがあるため使わない |
| 3 | 容量が大きい（約 5.5GB） | torch + CUDA 関連ライブラリが依存に含まれる。GPU なしでも CPU で動作する |
| 4 | venv は移動できない | 内部に絶対パスが埋め込まれているため mv で壊れる。場所を変えたい場合は作り直す |
| 5 | 初回変換時にモデルをダウンロード | Hugging Face からレイアウト解析・OCR モデルを自動取得する |
| 6 | pip キャッシュで再インストールが速い |
~/.cache/pip/wheels にキャッシュが残るため、venv を作り直しても再ダウンロード不要 |
まとめ
docling を WSL Ubuntu に venv で隔離してインストールする手順を紹介しました。ポイントは 3 つです。
- システム Python には入れず、必ず venv を使う（PEP 668 で保護されているため）
- ディスク容量に注意（依存含めて約 5.5GB）
- 初回変換時にモデルが自動ダウンロードされる（オフライン環境では事前取得が必要）
PDF やドキュメントをプログラムでテキスト化したい場面、特に RAG のデータ前処理として docling は便利な選択肢です。