🧠 概要

pypdf は PDF 操作用の定番ライブラリですが、
v5以降で破壊的変更が発生し、従来の PdfMerger が使えなくなりました。

しかも、v5にダウングレードしても非互換エラーが出るという報告が多発。
本記事では、その原因と、最新版でも確実に動作する Reader/Writer方式のコード例 を紹介します。

❌ よくあるエラー

v6 以降で：

ImportError: cannot import name 'PdfMerger' from 'pypdf'

v5 に落としても：

DeprecationWarning: PdfMerger is deprecated and will be removed
AttributeError: 'Merger' object has no attribute 'append'

つまり、v5でも動かないことがある！

🔍 なぜ v5 にしてもエラーが出るのか？

主な原因５つ

原因	説明
PyPDF2 との競合	古い `PyPDF2` が残って干渉している
モジュール名衝突	`pypdf.py` や `pdf.py` が同名ファイルとして存在
警告の例外化	`DeprecationWarning` が `error` に昇格して停止
仮想環境の混乱	`pip` と `python` の実行環境がずれている
キャッシュ汚染	`__pycache__` に旧バイトコードが残っている

🧹 環境のクリーンアップ手順

# 1️⃣ 競合パッケージ削除
python3 -m pip uninstall -y pypdf PyPDF2 PyPDF4 pypdf2

# 2️⃣ キャッシュ削除
find . -type d -name "__pycache__" -exec rm -rf {} +

# 3️⃣ 新しい仮想環境を作成
python3 -m venv .venv
source .venv/bin/activate   # Windowsは .venv\Scripts\activate

# 4️⃣ pypdfを再インストール
python -m pip install -U pypdf  # 最新版を推奨

# 5️⃣ 確認
python -m pip show pypdf PyPDF2

✅ 注意：pypdf.py というファイル名を自作していると、それが import されてしまう！

🧩 正しい解決策：Reader/Writerで結合する

from pypdf import PdfReader, PdfWriter

def merge_pdfs(output_path, *input_files):
    writer = PdfWriter()

    for path in input_files:
        with open(path, "rb") as f:
            reader = PdfReader(f)

            if getattr(reader, "is_encrypted", False):
                try:
                    reader.decrypt("")
                except Exception:
                    raise RuntimeError(f"Encrypted PDF not supported: {path}")

            for page in reader.pages:
                writer.add_page(page)

    with open(output_path, "wb") as out:
        writer.write(out)

    print(f"✅ 結合完了: {output_path}")

if __name__ == "__main__":
    merge_pdfs("merged.pdf", "a.pdf", "b.pdf", "c.pdf")

✅ このコードのメリット

PdfMerger / Merger に依存しない
v5 / v6 どちらでも動作
暗号化PDFにも対応
with構文でI/Oを安全に管理

🧪 実際の挙動（2025年時点）

バージョン	クラス	結果
pypdf 5.x	`PdfMerger`	⚠️ 動作不安定（環境次第で例外）
pypdf 6.x	`Merger`	❌ ImportError / append失敗
pypdf 6.x	`PdfReader` + `PdfWriter`	✅ 安定動作、今後も推奨

🧠 Pythonが破壊的変更を繰り返す理由

Pythonコミュニティは「後方互換性」よりも「コードの一貫性」を重視します。
これにより、ライブラリ開発者は古いAPIを削除しやすくなっています。

対策

requirements.txt でバージョン固定
CHANGELOG を定期的に確認
CIで警告を拾うようにする

🧾 まとめ

項目	内容
問題	v5でも `PdfMerger` / `Merger` が非互換で落ちる
原因	構造変更＋環境競合＋警告昇格
対策	Reader/Writerによる結合に移行
推奨	pypdf最新版 + 仮想環境クリーンセットアップ

🔗 参考リンク