PdfPecker

Python 向け pdfpecker

Python 用の高速な HTML／Markdown から PDF への変換、および PDF から画像やテキストへの変換ツールです。ブラウザーも依存関係も、インストールが必要な .NET もありません。

pip install pdfpecker

import pdfpecker

pdf = pdfpecker.html_to_pdf("<h1>Invoice 42</h1><p>Total: <b>1,250.00 EUR</b></p>")
pdfpecker.html_file_to_pdf("templates/invoice.html", "invoice.pdf")     # images and CSS resolve next to the file
pdfpecker.markdown_file_to_pdf("README.md", "readme.pdf")

pngs = pdfpecker.pdf_to_images(pdf, dpi=96)        # one PNG per page (or format="jpeg"/"webp")
text = pdfpecker.pdf_to_text(pdf)                  # pages separated by \f
both = pdfpecker.merge_pdfs([pdf, "terms.pdf"])

これは PdfPecker .NET ライブラリを事前コンパイルし、wheel に同梱したネイティブライブラリです。PdfPecker は独自の HTML パーサー、CSS エンジン、レイアウトエンジン、PDF ライター、PDF レンダラーを備えているため、1 ページの請求書なら変換に約 1 ミリ秒しかかからず、ブラウザーを起動することもありません。パッケージのバージョンは、内包するライブラリのバージョンです。PdfPecker のレンダリング内容、CSS のサポート、制限事項については、pdfpecker.net/docs をご覧ください。

プラットフォーム

Linux（glibc 2.28 以降および musl、x86-64 と ARM64）、macOS（Apple Silicon と Intel）、Windows（x64 と ARM64）向けの wheel を提供しています。対応する Python は 3.9 以降です。各 wheel のサイズは約 9 MB で、Python やシステムへの依存関係はありません。

速度

Python から、4 コアの Linux クラウド VM でウォームアップ後に計測したドキュメントあたりの中央値です。対象ドキュメントは、PdfPecker リポジトリのベンチマーク用ページです。

	請求書、1 ページ	機能紹介、5 ページ	レポート、29 ページ	起動から最初の PDF まで	PDF 1 件あたりのピークメモリ
pdfpecker	0.7 ms	2.9 ms	32 ms	57 ms	32 MB
Chromium 153 via Playwright	24 ms	48 ms	290 ms	735 ms	542 MB
xhtml2pdf 0.2.28	33 ms	209 ms	2.9 s	453 ms	63 MB
WeasyPrint 70.0	324 ms	797 ms	4.2 s	1.1 s	75 MB

API

すべての関数は、PDFについてバイト列またはパスを受け取り、失敗時にはPdfPeckerErrorのサブクラスを送出します。スレッドセーフで、処理中はGILを解放するため、スレッドで並列に変換できます。

関数	戻り値
html_to_pdf(html, **options)	HTMLのstrまたはUTF-8のbytesから生成したPDFのバイト列
html_file_to_pdf(path, output=None, **options)	PDFのバイト列。outputが指定されている場合はそこにも書き込みます。base_dirはファイルのフォルダーです
markdown_to_pdf(markdown, **options)	GitHubのテーブル、タスクリスト、取り消し線、脚注に対応したCommonMarkから生成したPDFのバイト列
markdown_file_to_pdf(path, output=None, **options)	html_file_to_pdfと同様です
pdf_to_images(pdf, dpi=150, format="png", pages=None, width=None, height=None, transparent=False, quality=None, password=None)	エンコードされた画像のリスト。各ページにつき1枚です
pdf_to_text(pdf, pages=None, password=None)	読み取り順のテキスト。ページは\fで区切られます
pdf_to_text_pages(pdf, pages=None, password=None)	各ページのテキストを格納したリスト
pdf_to_markdown(pdf, pages=None, include_links=True, include_annotations=True, include_images=False, page_comments=False, max_pages=None, password=None)	任意のPDFから、検索インデックスや言語モデル向けに、読み取り順の見出し、リスト、テーブルを含むGitHub Flavored Markdownを生成します
pdf_page_count(pdf, password=None)	ページ数
merge_pdfs(pdfs, title=None, author=None, bookmarks=True, creation_date=None)	複数のPDFを結合した1つのPDF
pdf_to_pdfa(pdf, output=None, conformance="PDF/A-2b")	任意のPDFをPDF/A-2b、-2u、-3b、-3uに変換し、pdf、changes、problems、is_conformantを含むPdfAResultとして返します
library_version()	内部のPdfPeckerライブラリのバージョン

pagesには、ページ番号、番号のリスト、または"1-3,5"、"8-"、"last"のような範囲を指定します。ページ番号は1から始まります。 すべての関数で、秒単位のtimeoutも指定できます。

HTML関数とMarkdown関数のオプション：

オプション	意味
base_dir	相対画像、スタイルシート、フォントのパスの基準となるフォルダーです。指定しない場合、文字列から作成したドキュメントはローカルファイルを読み込みません。
allow_file_access	base_dirの外にあるファイルもドキュメントから読み込めるようにします。信頼できるHTMLにのみ使用してください。
page_size, landscape	"A3"、"A4"（デフォルト）、"A5"、"Letter"、"Legal"、または(width_mm, height_mm)を指定します。CSSの@page { size }ルールが優先されます。
margin	ポイント単位（1インチあたり72ポイント）で指定します。数値1つ、または(top, right, bottom, left)を指定します。デフォルトは36です。CSSの@page { margin }が優先されます。
scale, shrink_to_fit	コンテンツを拡大・縮小します。ページ幅を超えるコンテンツは縮小されます（デフォルトで有効）。
header_text, footer_text	上または下の余白に表示するテキスト行です。{page}と{pages}は置き換えられます。CSSのマージンボックス（@top-centerなど）を使うと、さらに多くの設定が可能です。
fonts, use_system_fonts	CSSのfont-familyで指定できるTrueType/OpenTypeファイルまたはフォルダーを指定するか、インストール済みフォントからフォントファミリーを検索します。
title, author, subject, keywords, language	ドキュメントのプロパティです。
user_style_sheet	ドキュメント独自のスタイルシートの後に適用するCSSです。
creation_date	固定日付（datetime、date、またはUnix秒）を指定すると、実行ごとに出力のバイト列が同一になります。
conformance	"PDF/A-2b"、"PDF/A-3b"、"PDF/A-2u"、"PDF/A-3u"、"PDF/A-4"、または"PDF/A-4f"を指定します。
accessibility	"tagged"、"PDF/UA-1"、または"PDF/UA-2"を指定します。
compress, bookmarks, max_pages	ストリームを圧縮します（有効）。見出しからブックマークを作成します（有効）。指定したページ数を超える処理を停止します（100,000ページ）。

エラー：オプションが無効な場合はPdfPeckerArgumentError（ValueErrorでもあります）、読み取り可能なPDFでない入力にはPdfReadError、パスワードに関するエラーにはPdfPasswordError、max_pagesやサイズ制限に関するエラーにはPdfLimitError、PdfTimeoutError（TimeoutErrorでもあります）、および読み取れないフォントやファイルにはPdfFileError（OSErrorでもあります）が発生します。

AI エージェントとスキルからの利用

pdfpecker は、エージェントがサンドボックス内で作成して実行するコードに適しています。必要なのは pip install のみで、実行時にダウンロードするものはなく、ブラウザーを起動する必要もありません。エラーには問題の内容が示されます。エージェントには次の点を伝えてください。

• ドキュメントは CSS を含む HTML として作成し、ページサイズ、余白、ページ番号、柱は @page ルールに記述してください。たとえば、@page { size: A4; margin: 20mm; @bottom-center { content: "Page " counter(page) " of " counter(pages) } } のようにします。
• JavaScript は使えません。グラフは SVG または画像で作成してください。描画するスクリプトは使えません。
• 画像、スタイルシート、フォントは base_dir（または data: URI）から読み込みます。ネットワークから読み込むことはありません。
• 組み込みフォント（Helvetica、Times、Courier。含まれない文字を補うフォントも同梱）は、ラテン文字、ギリシャ文字、キリル文字に対応しています。それ以外の文字体系は疑問符で表示されます。中国語、日本語、アラビア語、ヘブライ語、ヒンディー語、タイ語を使う場合は、その文字体系に対応したフォントを fonts=[...] で指定するか、use_system_fonts=True を設定してください。
• 結果を確認するには、pdf_to_images(pdf, dpi=60) で PDF を画像に変換して各ページを見るか、pdf_to_text でテキストを読み取ってください。

MCP サーバー

このパッケージには Model Context Protocol サーバーが含まれているため、MCP に対応したチャットアプリやコーディングエージェントで PDF を作成し、ページを確認して、内容を読み取れます。stdio 経由で動作し、このパッケージ以外に必要なものはありません。

claude mcp add pdfpecker -- uvx pdfpecker mcp            # Claude Code

Claude Desktop や mcpServers 設定を読み込むその他のアプリでは、次のように設定します。

{ "mcpServers": { "pdfpecker": { "command": "uvx", "args": ["pdfpecker", "mcp", "--root", "/Users/me/Documents/pdfs"] } } }

ツール	説明
html_to_pdf	HTML（直接指定またはファイル）を PDF ファイルに変換し、レイアウト確認用に最初の数ページをプレビューします
markdown_to_pdf	Markdown を同様に変換します
render_pdf_pages	モデルが確認できるよう、最大 20 ページを PNG 画像に変換します
pdf_to_text	PDF のテキストをページごとに取得します
pdf_to_markdown	任意の PDF を Markdown に変換し、結果を返すかファイルに書き込みます
pdf_to_pdfa	任意の PDF を PDF/A に変換し、変更点と修正できなかった内容を示します
pdf_info	ページ数とファイルサイズを取得します
merge_pdfs	複数の PDF ファイルを 1 つにまとめます

ツールは、モデルがパスを指定するため、--root フォルダー（複数指定可能）の内部にあるファイルのみを読み書きします。既定値は現在のフォルダーです。ただし、チャットアプリでよくあるように、サーバーがファイルシステムのルートで起動した場合は ~/PdfPecker が既定値になります。python -m pdfpecker mcp を実行すると、uvx を使わずに同じサーバーを起動できます。

ソースからのビルド

wheel のネイティブライブラリは、PDFPECKER_VERSION で指定されたリリース済み PdfPecker NuGet パッケージからビルドされます。 .NET 10 SDK と NativeAOT の前提条件（Linux では clang、macOS では Xcode、Windows では Visual Studio C++ ツール）が必要です。

ci/build.sh linux-x64 manylinux_2_39_x86_64          # RID and wheel tag; builds, packs and tests the wheel

または、手動で dotnet publish native/PdfPecker.Native.csproj -c Release -r linux-x64 を実行し、pdfpecker_native.so （.dylib、.dll）を src/pdfpecker/ にコピーしてから、pytest を実行します。PDFPECKER_NATIVE_LIB を設定すると、別の場所にあるライブラリをパッケージから参照できます。

C ABI（native/Exports.cs）は、1 つの関数 pdfpecker_invoke(op, input, input_len, options_json, &output, &output_len, &error) に加えて、pdfpecker_free、pdfpecker_version、pdfpecker_abi_version で構成されているため、FFI に対応した他の言語からも同じライブラリを使用できます。

リリース

NuGet で PdfPecker をリリースした後、ここで PDFPECKER_VERSION を変更するプルリクエストを作成します。マージ後、オーナーが v<version> タグを付けて GitHub リリースを公開します。Wheels ワークフローが 8 つの wheel を再度ビルドし、タグと PDFPECKER_VERSION が一致することを確認したうえで、Trusted Publishing を使って PyPI にアップロードします。その後、公式 MCP Registry に MCP サーバーの新バージョン（server.json）を登録します。

ライセンス

MIT です。wheel には .NET ランタイム、zlib-ng、PdfPecker に同梱されているフォントとデータも含まれており、それぞれ独自のライセンスが適用されます。詳しくは THIRD-PARTY-NOTICES.md を参照してください。