🧠 概要
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最新版 + 仮想環境クリーンセットアップ |