【小ネタ】Claude Code で PDF を読ませるときにあると便利なツール

【小ネタ】Claude Code で PDF を読ませるときにあると便利なツール

Claude Code が PDF を読むときに使おうとしたツールについて、実際のログから何が起きたのかを整理します。環境に応じた最適な選択肢を知ることで、Claude Codeでの精度や処理速度が変わってくるので、参考にしてみてください。
2026.07.15

コーヒーが好きな emi です。

Claude Code に PDF を読み込ませていたら、Claude が pip install でツールをインストールしようとする場面に遭遇しました。

この記事では、Claude Code が PDF を読むときに使おうとした各種ツールがそれぞれ何をしているのか、ツールがない環境で実際に何が起きたのかを、手元のログを見ながら整理します。

あらかじめ PDF 読み込みツールを入れておくかどうかで、PDF を読ませたときの精度や速度が変わってくるので、環境を整える際の参考にしてください。

PDF 読み込みツール

最初に今回登場するツールを記載しておきます。

ツール 種類 役割 今回
pdfinfo poppler-utils(コマンド) メタ情報取得 環境に未インストールで使えず
pdftotext poppler-utils(コマンド) テキスト抽出 環境に未インストールで使えず
pdf2image Python ライブラリ(内部で poppler-utils を呼ぶ) 画像化(公式スキルで推奨) 候補にとどまり未使用
PyMuPDF(fitz) Python ライブラリ テキスト抽出・画像化 代替として採用

実際に起きたこと

見積書のような、表やレイアウトが重要な PDF を Claude Code に渡したときの話です。最初にこんな確認が出てきました。

 Bash command

   which pdftotext pdfinfo; pdfinfo "xx提案書.pdf" 2>&1
   Run shell command

 This command requires approval

 Do you want to proceed?
 ❯ 1. Yes
   2. Yes, and don’t ask again for: pdfinfo "xx提案書.pdf"
 ❯ 3. No

ほう、pdftotext やら pdfinfo やら便利なツールがあるらしい。インストールされているか確認し、あればそのパスを表示するみたいですが、私はインストールした覚えがないので、進めたらインストールしてくれるんでしょうか。Yes で進めてみます。

Bash command

python3 -c "import fitz; print('ok')" 2>&1; pip list 2>/dev/null | grep -i -E "pymupdf|pdf2image|pypdf"
Run shell command

This command requires approval

Do you want to proceed?
❯ 1. Yes
2. Yes, and don't ask again for python3 -c "import fitz; print('ok')" and pip list commands in /home/emiki/work/project/xx
3. No

ほう。急に Python コマンドを実行しようとしてきました。

コマンド解説
python3 -c "import fitz; print('ok')" 2>&1

これは fitz(PyMuPDF という PDF 操作ライブラリのモジュール名)がインポートできるか確認するコマンドです。成功すれば ok と表示され、なければエラーメッセージが表示されます。
2>&1 は標準エラー出力(2)を標準出力(1)と同じ出力先にまとめる(リダイレクトする)構文です。

pip list 2>/dev/null | grep -i -E "pymupdf|pdf2image|pypdf"

これはインストール済みの Python パッケージ一覧から、PDF 関連ライブラリ(pymupdfpdf2imagepypdf)を抜き出して表示します。
2>/dev/null は標準エラー出力(2)を非表示(/dev/null に捨てる)にする指定です。

これも確認・表示のみのコマンドだったので、Yes で進めてみます。

 Bash command

   pip install --user pymupdf 2>&1 | tail -20
   Run shell command

 This command requires approval

 Do you want to proceed?
 ❯ 1. Yes
   2. Yes, and don’t ask again for: pip install *
   3. No

 Esc to cancel · Tab to amend · ctrl+e to explain

インストールしようとしています。

コマンド解説
pip install --user pymupdf 2>&1 | tail -20

pip install --user pymupdf で PyMuPDF(PDF を操作する Python ライブラリ)を、ユーザー領域にインストールしようとしています。システム全体ではないところに少し良心があります。

2>&1 | tail -20 で、実行ログの最後の 20 行だけを表示するよう指定しています

前回のチェックで PyMuPDF が入っていなかったため、PDF を読むためにインストールしようとしているのだと思われます。

pymupdf は PyPI で公開されている、広く使われている正規のライブラリです。インストールは外部(PyPI)からパッケージをダウンロードする形で行われます。

pymupdf の実績について

PyPI のプロジェクトページによると、開発元は MuPDF を手がける Artifex Software, Inc.、開発ステータスは "5 - Production/Stable"(本番運用向けの安定版)です。ライセンスは AGPL 3.0 と Artifex の商用ライセンスから選べるデュアルライセンスで、オープンソース用途であれば無料で使えます。

pypistats.org のダウンロード統計では、月間ダウンロード数は1億回超、週間でも約2,400万回に上っており、広く使われているライブラリであることが確認できます。

なんで pdftotextpdfinfo を入れなかったのか気になりますが、これは後で聞いてみましょう。
pymupdf は広く使われているライブラリのようなので、このままインストールを進めてみます。

 Bash command

   mkdir -p /tmp/claude-1000/-home-emiki-work-project-xx/8e73f58d-79bd-4333-bc5d-c3bb68f1e69b/scratchpad/pdfpages
   python3 -c "
   import fitz
   doc = fitz.open('/home/emiki/work/project/xx/xx提案書.pdf')
   print('pages:', doc.page_count)
   for i, page in enumerate(doc):
       pix = page.get_pixmap(matrix=fitz.Matrix(1.5,1.5))
       pix.save(f'/tmp/claude-1000/-home-emiki-work-project-xx/8e73f58d-79bd-4333-bc5d-c3bb68f1e69b/scratchpad/pdfpages/page_{i+1:02d}.png')
   "

   Run shell command

 This command requires approval

 Do you want to proceed?
 ❯ 1. Yes
   2. Yes, and don't ask again for similar commands in /home/emiki/work/project/xx
   3. No

今回のコマンドは、先ほどインストールした PyMuPDF を使って、PDF の各ページを画像(PNG)に変換する処理です。

コマンド解説
mkdir -p /tmp/claude-1000/.../scratchpad/pdfpages

一時作業用フォルダ(/tmp 以下)を作成します。-p は途中のフォルダも含めてまとめて作る指定です。

その後の Python スクリプト(python3 -c から始まる部分)では、PDF を開いてページ数を表示(print('pages:', ...))し、各ページを 1.5 倍の解像度で画像化して、page_01.png, page_02.png... というファイル名で、作成した一時フォルダに保存します。

出力先は一時領域の /tmp で、元の PDF やプロジェクトファイルは変更されません。ネットワーク通信もなく、ローカルで完結する画像変換です。

Yes で進めると、Claude はそのまま「pdftotextpdfinfo も使えない」という前提で話を先に進めていったので、気になって「実際の出力はどうだったの?」と後から聞いてみました。返ってきた答えはこうです。

❯ pdftotext pdfinfoは使った?使わなかったのなら、使わなかった理由を教えてもらえます?

pdftotextとpdfinfoは最初に試しましたが、環境にpoppler-utilsが入っておらず(command not found)、sudo権限も使えなかったため実行できませんでした。代わりにpip install --user pymupdfでPythonライブラリを入れ、PDFの各ページを画像化して中身を確認しました(29ページ分レンダリングして目視確認済みです)。

which pdftotext pdfinfo の実際の出力が気になったので、追加で聞いてみます。

❯ which pdftotext pdfinfo の実際の出力は何だった?
  pdfinfo の出力(ページ数などのメタ情報)は取れていた?それとも取れなかった?

実際の出力はこうでした。

1回目(pdftotext -layout ... | head -300)
コマンド自体は 2>/dev/null でエラー出力を捨てていたため、ツールが存在せず失敗しても画面には何も表示されず「(Bash completed with no output)」という空の結果になりました。つまり中身は一切取れていません。

2回目(which pdftotext pdfinfo; pdfinfo ... 2>&1)
/bin/bash: line 1: pdfinfo: command not found
which の方は該当なしで無出力。pdfinfo は明確に「command not found」(exit code 127)でした。

なので結論として、ページ数などのメタ情報は pdfinfo からは一切取得できませんでした。poppler-utils が入っていなかったためです。ページ数(29ページ)は、その後 pip install --user pymupdf で入れた PyMuPDF (fitz) で doc.page_count を呼んで初めて取得しています。

念のため今もう一度同じコマンドを実行しましたが、結果は同じで pdfinfo: command not found でした。

3 つのツールの役割

このやり取りを見て、pdfinfopdftotext、PyMuPDF について調べてみました。

ツール 種類 主な用途
pdfinfo poppler-utils(コマンド) ページ数、サイズ、暗号化有無などのメタ情報取得
pdftotext poppler-utils(コマンド) テキスト抽出(-layout で見た目をある程度維持)
PyMuPDF(fitz) Python ライブラリ テキスト抽出、ページの画像化、座標情報の取得

文字が主体の契約書や議事録なら pdftotext が一番軽くて速いです。表や図面、見積書のようにレイアウトそのものに意味がある文書は、PyMuPDF で画像化して読ませると情報が維持できます。pdfinfo は本題に入る前に「何ページあるか」「暗号化されていないか」をさっと把握するのに便利です。

poppler-utils は OS のパッケージなので、私の WSL 環境では sudo 権限が必要でした。Claude Code はパスワードなしで sudo が実行できなかったので、pip install --user で入る PyMuPDF を採用した、というわけでした。

sudo が使える環境なら、最初から両方入れておくと Claude Code がドキュメントの性質に応じてどちらでも選べるようになります。

PyMuPDF での画像化は正確な反面、1 ページあたりのトークン消費が pdftotext に比べて大きくなります。今回も 29 ページを画像化しています。文字主体の文書まで律儀に画像化する必要はなく、まず pdftotext を試して、レイアウトが崩れる、あるいはテキストがそもそも取れない場合だけ画像化に切り替える、という優先順位にしておくのが精度とコストのバランスが良さそうです。

Claude Code 公式の PDF スキルでは

Claude Code 用に公開されている公式の PDF スキル(anthropics/skills)では、テキスト抽出はまず pdfplumber が推奨されていて、pdftotext はコマンドラインツールの一つとして紹介されているだけでした。PyMuPDF(fitz)は一度も登場しません。

画像化やスキャン PDF の OCR には pdf2image が使われており、これは内部で poppler-utilspdftoppm を呼び出す仕組みです。

今回 Claude Code が選んだ「pdftotext → PyMuPDF」という組み合わせは、公式スキルの定石をなぞったものではなく、その場の環境(poppler-utils が無く、sudo も使えない)に対する、その場限りの現実的な対応だったということです。記録として残しておきます。

おわりに

まず入れておくと良いのは poppler-utils です。pdfinfo でメタ情報を確認し、文字主体の文書は pdftotext、レイアウトが重要な文書は pdf2image で画像化できます。which pdftotext pdfinfo pdftoppm で入っているか確認してみてください。poppler-utils が使えない環境では、今回のように PyMuPDF が代替になります。

本記事への質問やご要望については画面下部の「DevelopersIOへのご意見」からお問い合わせいただけます。

参考

https://dev.classmethod.jp/articles/ai-coding-agent-read-pdf-file/

https://note.com/mizupe/n/ndce1049b49c5

https://qiita.com/rihib/items/f06074bc1304d5a9e64b


Claudeならクラスメソッドにお任せください

クラスメソッドは、Anthropic社とリセラー契約を締結しています。各種製品ガイドから、業種別の活用法、フェーズごとのお悩み解決などサービス支援ページにまとめております。まずはご覧いただき、お気軽にご相談ください。

サービス詳細を見る

この記事をシェアする

AI白書

関連記事