pdfpecker for Rust

Fast HTML and Markdown to PDF, and PDF to images, text and Markdown, for Rust. No browser, no Chromium download, no .NET to install, and no runtime dependencies.

cargo add pdfpecker

use pdfpecker::{ImageOptions, PageSize, PdfOptions, TextOptions};

let pdf = pdfpecker::html_to_pdf("<h1>Invoice 42</h1><p>Total: <b>1,250.00 EUR</b></p>", &PdfOptions::new())?;
std::fs::write("invoice.pdf", &pdf)?;

// Images and CSS resolve next to the file.
let invoice = pdfpecker::html_file_to_pdf("templates/invoice.html", &PdfOptions::new())?;
let readme = pdfpecker::markdown_file_to_pdf("README.md", &PdfOptions::new().page_size(PageSize::Letter))?;

let pngs = pdfpecker::pdf_to_images(&pdf, &ImageOptions::new().dpi(96.0))?; // one PNG per page
let text = pdfpecker::pdf_to_text(&pdf, &TextOptions::new())?;               // pages separated by \f
let both = pdfpecker::merge_pdfs(&[&invoice, &readme], &Default::default())?;

This is the PdfPecker .NET library, compiled ahead of time into a native library: the same library the Python and npm packages ship. PdfPecker has its own HTML parser, CSS engine, layout engine, PDF writer and PDF renderer, so a one-page invoice takes under a millisecond and no browser ever starts. It runs no JavaScript in the documents and never goes online: images, stylesheets and fonts load from base_dir. The crate version is the library version it holds. Documentation of what PdfPecker renders, its CSS support and its limitations: pdfpecker.net/docs.

Platforms and deployment

Rust 1.85 or later on Linux (glibc 2.28+ and musl, x64 and arm64), macOS 12+ (Apple Silicon and Intel) and Windows (x64 and arm64).

The build script downloads the target's native library from the pdfpecker wheel on PyPI (about 9 MB, once; it is kept in your cache folder) with curl or wget, and checks the wheel and the library against SHA-256 values that the crate carries. cargo run and cargo test then find it on their own. To ship a program, copy the library next to the executable:

pdfpecker::library_path() returns the file that was loaded. The library is looked for in PDFPECKER_NATIVE_LIB (a file path), then next to the executable, then where the build put it.

On musl (Alpine), the program must be linked dynamically to load the library: build with RUSTFLAGS="-C target-feature=-crt-static". The build stops with that advice otherwise.

Speed

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

Conversions run in parallel from several threads: 6,600 invoices a second on the 4 cores.

API

Every function returns pdfpecker::Result. PDFs are given as &[u8]; options are built with chained methods from ::new() or Default::default().

pages takes a page number (3), an array or Vec ([1, 3]), a range (2..=4) or a string such as "1-3,5" or "last", numbered from 1. Every call that reads or writes a document also takes a timeout.

Options of the HTML and Markdown functions (PdfOptions):

Errors carry an ErrorKind: InvalidArgument (a bad option value, a page past the end), Unreadable (not a readable PDF, image or font), Password, Limit, Timeout, Failed, Io (a font or image file that could not be read), Library (the native library is missing or does not fit) and Internal.

Every function is safe to call from several threads at once. The calls block, so async code runs them with tokio::task::spawn_blocking or its runtime's equivalent.

Building from this repository

The crate uses the native libraries in the Python package's wheels on PyPI, which are built from the released PdfPecker NuGet package; nothing is compiled from .NET here.

cargo test                               # downloads this machine's library on the first build
ci/test.sh                               # also packages the crate and tests it as a dependency
python3 scripts/update-wheels.py         # after changing the version in Cargo.toml: writes wheels.txt

Releasing

After a PdfPecker release reaches PyPI (the Python package follows each NuGet release), a pull request here changes version in Cargo.toml, runs scripts/update-wheels.py and adds functions or options for what the release added. The owner then publishes a GitHub release tagged v<version>; the CI workflow tests every platform and publishes the crate to crates.io.

License

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