PdfPecker

pdfpecker for Python

Fast HTML and Markdown to PDF, and PDF to images and text, for Python. No browser, no dependencies, no .NET to install.

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 filepdfpecker.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 \fboth = pdfpecker.merge_pdfs([pdf, "terms.pdf"])

This is the PdfPecker .NET library, compiled ahead of time into a native library that ships inside the wheel. PdfPecker has its own HTML parser, CSS engine, layout engine, PDF writer and PDF renderer, so a conversion takes about a millisecond for a one-page invoice and never starts a browser. The package version is the library version it holds. Documentation of what PdfPecker renders, its CSS support and its limitations: pdfpecker.net/docs.

Platforms

Wheels for Linux (glibc 2.28+ and musl, x86-64 and ARM64), macOS (Apple Silicon and Intel) and Windows (x64 and ARM64), on Python 3.9 and later. Each wheel is about 9 MB and has no Python or system dependencies.

Speed

From Python, on a 4-core Linux cloud VM, median time per document after warm-up; the documents are the benchmark pages of the PdfPecker repository:

API

Every function takes bytes or a path for PDFs, raises a subclass of PdfPeckerError on failure, is thread-safe and releases the GIL while it works, so threads convert in parallel.

pages takes a page number, a list of numbers, or a range such as "1-3,5", "8-" or "last", numbered from 1. Every function also takes timeout in seconds.

Options of the HTML and Markdown functions:

Errors: PdfPeckerArgumentError (also a ValueError) for bad options, PdfReadError for input that is not a readable PDF, PdfPasswordError, PdfLimitError for max_pages and the size limits, PdfTimeoutError (also a TimeoutError) and PdfFileError (also an OSError) for a font or file that cannot be read.

Using it from AI agents and skills

pdfpecker suits code that an agent writes and runs in a sandbox: one pip install, nothing to download at run time, no browser to launch, and errors that say what went wrong. A few things to tell the agent:

• Write the document as HTML with CSS; put page size, margins, page numbers and running headers in @page rules, for example @page { size: A4; margin: 20mm; @bottom-center { content: "Page " counter(page) " of " counter(pages) } }.
• There is no JavaScript: charts must be SVG or images, not a script that draws them.
• Images, stylesheets and fonts load from base_dir (or data: URIs), never from the network.
• The built-in fonts (Helvetica, Times and Courier, with bundled fallback fonts for the letters they lack) cover Latin, Greek and Cyrillic; other scripts come out as question marks. For Chinese, Japanese, Arabic, Hebrew, Hindi or Thai, pass fonts=[...] with a font that covers the script, or use_system_fonts=True.
• To check a result, render it back with pdf_to_images(pdf, dpi=60) and look at the pages, or read it with pdf_to_text.

MCP server

The package includes a Model Context Protocol server, so chat apps and coding agents that speak MCP can make PDFs, look at their pages and read them. It runs over stdio and needs nothing but this package:

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

For Claude Desktop and other apps that read an mcpServers setting:

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

The tools read and write files only inside the --root folders (repeatable), because the model picks the paths. The default is the current folder, or ~/PdfPecker when the server starts in the filesystem's root, as chat apps often do. python -m pdfpecker mcp runs the same server without uvx.

Building from source

The wheel's native library is built from the released PdfPecker NuGet package named in PDFPECKER_VERSION. It needs the .NET 10 SDK with the NativeAOT prerequisites (clang on Linux, Xcode on macOS, the Visual Studio C++ tools on Windows):

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

Or by hand: dotnet publish native/PdfPecker.Native.csproj -c Release -r linux-x64, copy pdfpecker_native.so (.dylib, .dll) into src/pdfpecker/, and run pytest. PDFPECKER_NATIVE_LIB points the package at a library elsewhere.

The C ABI (native/Exports.cs) is one function, pdfpecker_invoke(op, input, input_len, options_json, &output, &output_len, &error), plus pdfpecker_free, pdfpecker_version and pdfpecker_abi_version, so other languages with an FFI can use the same library.

Releasing

A PdfPecker release on NuGet is followed by a pull request here that changes PDFPECKER_VERSION. Once it is merged, the owner publishes a GitHub release tagged v<version>; the Wheels workflow builds the eight wheels again, checks the tag against PDFPECKER_VERSION and uploads them to PyPI with Trusted Publishing. It then lists the new version of the MCP server (server.json) in the official MCP Registry.

License

MIT. The wheel also contains the .NET runtime, zlib-ng and the fonts and data PdfPecker bundles, each under its own license: see THIRD-PARTY-NOTICES.md.