PyMuPDFは、Pythonプログラミング言語で使用できる非常に強力なライブラリです。このライブラリの真価は、PDFファイルだけでなく、XPS、EPUB、さらには画像ファイルなど、多岐にわたるドキュメント形式を扱える点にあります。PyMuPDFは、もともとC言語で書かれた高性能なレンダリングエンジン「MuPDF」をPythonから簡単に利用できるようにしたものです（「Pythonバインディング」と呼ばれます）。これにより、Pythonの書きやすさと、MuPDFの高速な処理能力の両方の恩恵を受けることができます。😊

このライブラリは、Artifex Software社によって開発・維持されており、オープンソース（AGPLライセンス）と商用ライセンスの両方で提供されています。特に、ドキュメントからのデータ抽出、分析、変換、そして編集といった多様な操作を、高いパフォーマンスで実行できることが大きな特徴です。

少し歴史的な話をすると、PyMuPDFをインポートする際にはimport fitzという名前が使われることがあります。これは、MuPDFの初期のグラフィックライブラリ名「Fitz」に由来する名残です。最近のバージョンではimport pymupdfが推奨されていますが、後方互換性のためにfitzも利用可能です。

このブログ記事では、PyMuPDFの基本的な概念から、具体的な使い方、そして応用的な機能まで、幅広く解説していきます。PDF操作の自動化や、ドキュメントからの情報抽出など、あなたのプロジェクトに役立つ情報がきっと見つかるはずです。🚀

PyMuPDFの主な特徴 ✨

インストール方法 💻

PyMuPDFのインストールは非常に簡単です。Pythonのパッケージ管理ツールであるpipを使用します。Python 3.9以降が必要です（2025年初頭時点）。

ターミナルまたはコマンドプロンプトを開き、以下のコマンドを実行してください。

pip install --upgrade pymupdf

通常、これにより、お使いのOSとPythonバージョンに対応した「ホイール（wheel）」ファイルがダウンロードされ、スムーズにインストールが完了します。

仮想環境の利用推奨: プロジェクトごとにライブラリのバージョンを管理するために、Pythonの仮想環境（例: `venv`）内でインストールすることが強く推奨されます。

# Windowsの場合
python -m venv myenv
.\myenv\Scripts\activate
python -m pip install --upgrade pip
pip install pymupdf

# macOS / Linux の場合
python3 -m venv myenv
source myenv/bin/activate
python -m pip install --upgrade pip
pip install pymupdf

基本的な使い方 🚀

PyMuPDFの基本的な操作を見ていきましょう。ここでは、PDFファイルを開き、ページ数を取得し、テキストや画像を抽出する簡単な例を示します。

ライブラリのインポート

まず、ライブラリをインポートします。前述の通り、pymupdf または fitz の名前でインポートできます。ここではfitzを使用します。

import fitz  # PyMuPDF ライブラリをインポート (pymupdf でも可)
import os

PDFファイルを開く

fitz.open() 関数を使ってPDFファイルを開きます。引数にファイルパスを指定します。ファイルパスを指定しない場合は、新しい空のPDFドキュメントがメモリ上に作成されます。

# サンプルPDFファイルへのパス (適宜変更してください)
pdf_path = "example.pdf"

# PDFファイルが存在するか確認
if not os.path.exists(pdf_path):
    print(f"エラー: ファイルが見つかりません - {pdf_path}")
    # ここで処理を中断するか、サンプルPDFを作成するなどの対応が必要
    # 例として、ここでは空のPDFを作成してみます
    doc = fitz.open() # 新しい空のPDFを作成
    page = doc.new_page()
    page.insert_text((50, 72), "This is a sample PDF.")
    doc.save("example.pdf")
    print("サンプルPDF 'example.pdf' を作成しました。")
    doc.close()
    doc = fitz.open(pdf_path) # 再度開く
else:
    try:
        doc = fitz.open(pdf_path)
        print(f"'{pdf_path}' を開きました。")
    except Exception as e:
        print(f"ファイルを開けませんでした: {e}")
        # エラー処理
        exit() # 例: プログラム終了

# メモリ上のバイトデータから開く場合
# with open(pdf_path, "rb") as f:
#     pdf_data = f.read()
# doc_mem = fitz.open(stream=pdf_data, filetype="pdf")

fitz.open() は Document オブジェクトを返します。このオブジェクトを通してドキュメントに対する様々な操作を行います。

ドキュメント情報の取得

開いたドキュメントの基本的な情報を取得できます。

# ページ数を取得
page_count = doc.page_count
print(f"ページ数: {page_count}")

# メタデータ（タイトル、作成者など）を取得
metadata = doc.metadata
print("メタデータ:")
if metadata:
    for key, value in metadata.items():
        print(f"  {key}: {value}")
else:
    print("  メタデータはありません。")

# 目次（ブックマーク）を取得
toc = doc.get_toc()
print("目次:")
if toc:
    for item in toc:
        level, title, page_num = item[:3] # 基本的な情報を取得
        print(f"  {'  ' * (level - 1)}[{page_num}] {title}")
else:
    print("  目次はありません。")

get_toc() はリストのリストを返します。各内部リストは [階層レベル, タイトル, ページ番号, その他の情報...] という形式です。

ページの操作とテキスト抽出

特定のページにアクセスし、そこからテキストを抽出します。ページは0から始まるインデックスで指定します。

if page_count > 0:
    # 最初のページを取得 (インデックスは0)
    # page = doc.load_page(0)
    page = doc[0] # この形式でも取得可能

    # ページからテキストを抽出 (プレーンテキスト)
    text = page.get_text()
    print("\n最初のページのテキスト (一部):")
    print(text[:500] + "...") # 長い場合に備えて最初の500文字だけ表示

    # 他の形式でテキストを抽出
    # html_text = page.get_text("html")
    # json_text = page.get_text("json")
    # dict_text = page.get_text("dict") # 詳細情報を含む辞書
else:
    print("ドキュメントにページがありません。")

get_text() メソッドは、引数によって様々な形式（”plain”, “html”, “xml”, “json”, “dict”, “words”, “blocks”）でテキストを抽出できます。デフォルトは “plain” です。”dict” や “json” を使うと、文字の位置、フォント、色などの詳細な情報を取得できます。

画像の抽出

ページに含まれる画像を抽出することも簡単です。

if page_count > 0:
    page = doc[0] # 例として最初のページを使用

    # ページ内の画像情報を取得
    image_list = page.get_images(full=True)

    if image_list:
        print(f"\n最初のページには {len(image_list)} 個の画像が見つかりました。")
        # 最初の画像を抽出して保存してみる
        img_info = image_list[0]
        xref = img_info[0] # 画像の内部参照番号
        base_image = doc.extract_image(xref)
        image_bytes = base_image["image"] # 画像データ (bytes)
        image_ext = base_image["ext"] # 画像の拡張子 (例: "png", "jpeg")

        # 画像をファイルに保存
        output_image_path = f"extracted_image_p1_i1.{image_ext}"
        with open(output_image_path, "wb") as img_file:
            img_file.write(image_bytes)
        print(f"画像を '{output_image_path}' として保存しました。")
    else:
        print("\n最初のページに画像は見つかりませんでした。")

    # ドキュメント全体の画像を抽出する別の方法 (ページに表示されていなくても抽出可能)
    # for img_index, img in enumerate(doc.get_page_images(0)): # 最初のページの場合
    #     xref = img[0]
    #     ... (上記と同様の処理) ...

page.get_images(full=True) は、そのページで参照されている画像のリストを返します。doc.extract_image(xref) を使うと、画像のバイナリデータや拡張子などを取得できます。

ドキュメントを閉じる

操作が終わったら、ドキュメントを閉じることが推奨されます。

doc.close()
print("\nドキュメントを閉じました。")

または、with構文を使うと自動的に閉じられます。

try:
    with fitz.open(pdf_path) as doc:
        print(f"\n再度 '{pdf_path}' を開きました (with構文)。")
        page_count = doc.page_count
        print(f"ページ数: {page_count}")
        # ... ここで他の操作 ...
    print("ドキュメントは自動的に閉じられました。")
except Exception as e:
    print(f"ファイルを開けませんでした: {e}")

高度な機能と応用例 🛠️

PyMuPDFは基本的な操作に加えて、さらに高度な機能も提供しています。ここではいくつかの例を紹介します。

PDFの変更と保存

既存のPDFに変更を加えたり、新しいPDFを作成したりできます。

try:
    with fitz.open("example.pdf") as doc: # 既存のファイルを開く (なければ作成される)
        if doc.page_count > 0:
            page = doc[0] # 最初のページ

            # ページにテキストを追加
            text_to_add = "これはPyMuPDFによって追加されたテキストです！"
            insert_pos = fitz.Point(50, 100) # 挿入位置 (左下の座標)
            page.insert_text(insert_pos, text_to_add, fontsize=12, color=(1, 0, 0)) # 赤色で追加

            # ページに図形を描画 (矩形)
            rect_to_draw = fitz.Rect(50, 120, 250, 150) # 矩形の座標 (左上、右下)
            page.draw_rect(rect_to_draw, color=(0, 0, 1), fill=(0.8, 0.8, 1), width=1.5, dashes="[3 2]") # 青枠、薄い青で塗りつぶし、破線

            # 注釈（ハイライト）を追加
            highlight_rect = page.search_for("sample")[0] # "sample" というテキストを探す
            if highlight_rect:
                highlight = page.add_highlight_annot(highlight_rect)
                highlight.set_colors(stroke=(1, 1, 0)) # ハイライト色を黄色に
                highlight.update() # 変更を適用

            # 変更を保存 (新しいファイルとして)
            output_pdf_path = "example_modified.pdf"
            doc.save(output_pdf_path, garbage=4, deflate=True) # garbage=4で不要なオブジェクトを削除, deflateで圧縮
            print(f"変更を加えたPDFを '{output_pdf_path}' として保存しました。")

            # 上書き保存する場合 (注意: 元のファイルが変更されます)
            # doc.saveIncr()
            # print("変更を元のファイルに上書き保存しました。")
        else:
            print("ページがないため変更できませんでした。")

except Exception as e:
    print(f"PDFの変更中にエラーが発生しました: {e}")

save()メソッドには、ガベージコレクションのレベル(garbage)、圧縮(deflate)、線形化(linear)などのオプションを指定でき、ファイルサイズや読み込み速度を最適化できます。

ページの結合と分割

複数のPDFを結合したり、一つのPDFを複数のページに分割したりすることも可能です。

# PDF結合の例
pdf1_path = "example.pdf"
pdf2_path = "example_modified.pdf" # 先ほど作成したファイル
output_merged_path = "merged_document.pdf"

try:
    # 新しい空のPDFを作成
    merged_doc = fitz.open()

    # 結合したいPDFを開く
    doc1 = fitz.open(pdf1_path)
    doc2 = fitz.open(pdf2_path)

    # 最初のPDFのページを挿入
    merged_doc.insert_pdf(doc1)

    # 二番目のPDFのページを挿入
    merged_doc.insert_pdf(doc2)

    # 結合したPDFを保存
    merged_doc.save(output_merged_path)
    print(f"'{pdf1_path}' と '{pdf2_path}' を結合し、'{output_merged_path}' として保存しました。")

    # ドキュメントを閉じる
    doc1.close()
    doc2.close()
    merged_doc.close()

except Exception as e:
    print(f"PDFの結合中にエラーが発生しました: {e}")

# PDF分割の例 (各ページを個別のPDFとして保存)
input_split_path = "merged_document.pdf"

try:
    with fitz.open(input_split_path) as doc:
        print(f"'{input_split_path}' を分割します...")
        for i in range(doc.page_count):
            # 新しい単一ページのPDFを作成
            single_page_doc = fitz.open()
            single_page_doc.insert_pdf(doc, from_page=i, to_page=i)

            # 個別のファイルとして保存
            output_split_path = f"split_page_{i + 1}.pdf"
            single_page_doc.save(output_split_path)
            single_page_doc.close()
        print(f"{doc.page_count} 個のファイルに分割しました。")

except Exception as e:
    print(f"PDFの分割中にエラーが発生しました: {e}")

insert_pdf() メソッドを使うと、他のPDFドキュメントのページを簡単に挿入できます。ページの範囲指定や回転なども可能です。

テキスト検索とハイライト

特定のキーワードを検索し、その場所（矩形座標）を取得したり、ハイライトしたりできます。

search_term = "PyMuPDF"
highlight_output_path = "highlighted_search.pdf"

try:
    with fitz.open("example_modified.pdf") as doc:
        found_count = 0
        for page_num, page in enumerate(doc):
            # ページ内でテキストを検索
            found_rects = page.search_for(search_term) # Rectオブジェクトのリストを返す

            if found_rects:
                print(f"ページ {page_num + 1} で '{search_term}' が {len(found_rects)} 回見つかりました。")
                found_count += len(found_rects)
                # 見つかった箇所すべてにハイライト注釈を追加
                for rect in found_rects:
                    highlight = page.add_highlight_annot(rect)
                    highlight.update() # 注釈を確定

        if found_count > 0:
            doc.save(highlight_output_path)
            print(f"検索結果をハイライトしたPDFを '{highlight_output_path}' として保存しました。")
        else:
            print(f"'{search_term}' はドキュメント内で見つかりませんでした。")

except Exception as e:
    print(f"テキスト検索とハイライト中にエラーが発生しました: {e}")

ページを画像としてレンダリング

PDFのページを画像ファイル（PNGなど）として保存できます。解像度やクリッピング領域も指定可能です。

render_output_path = "rendered_page_1.png"
dpi = 300 # 解像度 (dots per inch)

try:
    with fitz.open("example_modified.pdf") as doc:
        if doc.page_count > 0:
            page = doc[0] # 最初のページ

            # ページをPixmapにレンダリング
            # matrix = fitz.Matrix(dpi / 72, dpi / 72) # スケーリング行列 (デフォルトは72dpi)
            pix = page.get_pixmap(dpi=dpi)

            # PixmapをPNGファイルとして保存
            pix.save(render_output_path)
            print(f"最初のページを解像度 {dpi} dpi で '{render_output_path}' として保存しました。")

            # SVG (ベクター形式) で保存する場合
            # svg_output_path = "rendered_page_1.svg"
            # svg_text = page.get_svg_image()
            # with open(svg_output_path, "w") as f:
            #     f.write(svg_text)
            # print(f"最初のページを '{svg_output_path}' として保存しました。")
        else:
            print("レンダリングするページがありません。")

except Exception as e:
    print(f"ページのレンダリング中にエラーが発生しました: {e}")

ユースケースと活用例 💡

PyMuPDFの多機能性と高速性により、様々な分野で活用されています。

例えば、2023年頃からは、LLMを活用したシステム（RAGなど）が注目されており、その前処理段階でPDFから高品質なテキストや構造化データを抽出するためにPyMuPDF（特にPyMuPDF4LLM）が活用されるケースが増えています。

パフォーマンスと考慮事項 🤔

まとめ 🏁

PyMuPDFは、PythonでPDFやその他の多様なドキュメント形式を扱うための、非常に強力で高速、かつ多機能なライブラリです。テキストや画像の抽出、ドキュメントの編集・作成、ページの操作、レンダリングなど、幅広いタスクに対応できます。

インストールも簡単で、基本的な使い方も直感的ですが、高度な機能やオプションも豊富に用意されており、複雑な要件にも応えることができます。特にパフォーマンスが要求される場面や、LLM連携など最新の技術トレンドにおいても、その価値を発揮します。

このガイドが、PyMuPDFを使い始めるきっかけとなり、あなたのプロジェクトにおけるドキュメント処理の効率化に貢献できれば幸いです。ぜひ、公式ドキュメントも参照しながら、PyMuPDFの可能性を探求してみてください！ 🎉