pdfboss

A PDF engine written from scratch in Rust: parse, extract text and images, rasterize to PNG, PPM, BMP or JPEG, create PDFs. One core, a CLI, and pythonic bindings.

Docs · PyPI · crates.io · Benchmarks

Reading a PDF should not require a C library. pdfboss is a clean-room reader built from the ISO 32000 specification: safe Rust, no C dependencies, no bindings to another engine, one core behind the CLI and the native Python extension. It is a lenient reader: real-world files are damaged, so it reconstructs broken cross-reference tables, tolerates wrong stream lengths, and skips garbage operators instead of refusing.

Highlights

• Clean-room engine: implemented from the ISO 32000 specification in safe Rust; no C dependencies, no bindings to another engine.
• Fastest text extraction measured: 7,477 pages/s over a 40-file real-world corpus, about 18× the C-backed PyMuPDF (benchmarks).
• Its own codecs: JPEG 2000, JBIG2, CCITT and ICC are decoded in-tree, implemented from their specifications, not linked in.
• Four render formats: PNG through its own page-tuned encoder, PPM and BMP as the raw pixels behind a header (about 0.3 ms a page, for pipelines that consume the pixels right away), and JPEG from its own baseline encoder with a quality knob; picked by format= in Python and by the -o extension on the CLI (guide).
• Embedded-image extraction: every image a page draws, at native size, alpha applied, from the CLI, Python and Rust (example).
• PDF creation: document structs, a canvas painter and a COS writer with deterministic output; CommonMark+GFM composes into CSS-themed PDFs from the CLI, Python and Rust (example).
• Async, range-fetching I/O: documents open over files or http(s):// URLs and fetch only the byte ranges they need, never the whole file.
• Lenient, and it says so: broken cross-references are reconstructed and unreadable content is skipped, with every dropped or approximated item reported.
• Terminal explorer (pdfboss tui): element tree, object inspector, hex view, page and Markdown previews.

Install

pip install pdfboss           # prebuilt abi3 wheels (CPython 3.12+), no toolchain required
cargo install pdfboss-cli     # the `pdfboss` binary

Usage

pdfboss info    report.pdf                 # version, page count, sizes, metadata
pdfboss text    report.pdf --page 2        # extract text (omit --page for all)
pdfboss md      report.pdf                 # markdown: headings, lists, tables from layout
pdfboss render  report.pdf --page 1 -o page.png --scale 2.0   # or .ppm / .bmp / .jpg
pdfboss images  report.pdf                 # extract embedded images as native-size PNGs
pdfboss tui     report.pdf                 # interactive terminal explorer
pdfboss create blank  -o out.pdf --pages 3    # new PDF: empty pages
pdfboss create text   notes.txt -o out.pdf    # new PDF: word-wrapped text
pdfboss create images a.png b.jpg -o out.pdf  # new PDF: one page per image
pdfboss create md     notes.md -o out.pdf     # new PDF: markdown composed with a CSS theme
pdfboss create manifest q3.toml -o out.pdf    # new PDF: TOML manifest (metadata, pages, text, paragraphs, images, links)

import pdfboss

doc = pdfboss.Document("report.pdf")       # or Document(data=raw_bytes)
text = doc.extract_text()
md   = doc.extract_markdown()              # headings, lists and tables inferred from layout
png  = doc[0].render(scale=2.0)            # PNG bytes; format="ppm"/"bmp" for raw pixels, "jpeg" for lossy
imgs = doc[0].extract_images()             # embedded images: .data (PNG), .width, .height
pdf  = pdfboss.md.to_pdf(open("notes.md").read())  # markdown -> themed PDF bytes

pdfboss.write composes a Pdf from Python: pages and elements join with |, and save/to_bytes builds the file bytes once:

from pdfboss.write import Link, Metadata, Page, Paragraph, Pdf, Standard14, Text
cover = (
    Page(size="a4")
    | Text("Q3 Report", at=(72, 770), font=Standard14.HELVETICA_BOLD, size=28)
    | Paragraph("Prepared for the board.", rect=(72, 700, 500, 740))
    | Link(rect=(72, 60, 200, 80), url="https://example.com/q3")
)
data = (Pdf() | Metadata(title="Q3 Report") | cover).to_bytes()

An Outline of nested Bookmarks becomes the document's bookmark panel (Pdf.outline); Attachment objects embed arbitrary files inside the document (Pdf.attachments); PageLabel ranges control how page numbers render in viewer UI (Pdf.page_labels); and a Viewer sets the document's opening layout, mode, and page (Pdf.viewer). Each slots into Pdf with |, exactly like Metadata.

Existing files are watermarked in place: pdfboss.write.watermark(data, overlay) returns data with the first page of overlay drawn over every page, as an incremental update appended to the original bytes, so the result grows by the overlay page's size and takes no longer than parsing the two files. rewrite=True writes a fresh, compressed file instead, which usually comes out smaller than the original.

pdfboss json    report.pdf                    # dump the document as a JSON value tree
pdfboss json    report.pdf --layout           # ...plus per-page layout blocks
pdfboss hex     report.pdf obj:5              # hexdump the file or a selected element
pdfboss q       report.pdf '.header.version'  # jq-style queries over the JSON tree
pdfboss obj     report.pdf 5                  # pretty-print object 5

page = doc[0]
print(page.width, page.height, page.rotation)

for element in doc.elements():             # lazy: physical + logical, byte spans included
    print(element.kind, element.span)

# Async access over files or http(s) URLs, without reading the whole document.
doc = await pdfboss.AsyncDocument.open_url("https://example.com/report.pdf")
async for element in doc.elements():
    print(element.kind, element.value())

use pdfboss_core::Document;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    let page = doc.page(0)?;

    let text = pdfboss_output::extract_text(&doc, &page)?;
    let markdown = pdfboss_output::extract_markdown(&doc)?;
    println!("{text}\n{markdown}");

    let pixmap = pdfboss_render::render_page(&doc, &page, 2.0)?;
    pixmap.save_png("page.png")?;

    let images = pdfboss_render::extract_page_images(&doc, &page)?;
    println!("{} embedded images", images.len());
    Ok(())
}

Extract embedded images

pdfboss images, Page.extract_images() and pdfboss_render::extract_page_images decode every image a page draws (inline images included) at the image's own pixel dimensions, in drawing order, with /SMask alpha applied. An image drawn twice appears twice, and stencil masks (/ImageMask true) paint a fill color rather than carrying pixels of their own, so they are skipped.

Real pages draw one-pixel strips and spacers; a size filter keeps the pictures:

import pdfboss

doc = pdfboss.Document("report.pdf")
for index in range(len(doc)):
    for n, image in enumerate(doc[index].extract_images()):
        if image.width < 64 or image.height < 64:
            continue
        with open(f"page-{index}-img-{n}.png", "wb") as out:
            out.write(image.data)

The same walk from Rust, one Pixmap per image:

use pdfboss_core::Document;
use pdfboss_render::extract_page_images;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    for index in 0..doc.page_count() {
        let page = doc.page(index)?;
        for (n, image) in extract_page_images(&doc, &page)?.iter().enumerate() {
            if image.width < 64 || image.height < 64 {
                continue;
            }
            image.save_png(format!("page-{index}-img-{n}.png"))?;
        }
    }
    Ok(())
}

Create PDFs

pdfboss-write is the write-side twin of the reader: plain structs compose the document (Pdf, Page, PageSize), a Canvas paints content, and a COS-level writer serializes it. Output is deterministic: the same input produces byte-identical files, and the crate never reads clocks or randomness, so dates appear only when supplied.

use pdfboss_write::{Color, ImageData, Page, PageSize, Pdf, Standard14};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut page = Page::new(PageSize::A4);
    let canvas = &mut page.canvas;

    canvas.text("Quarterly report", 72.0, 760.0, Standard14::HelveticaBold, 24.0)?;

    canvas.set_fill(Color::Rgb(0.13, 0.45, 0.85));
    canvas.rect(72.0, 744.0, 451.0, 4.0);
    canvas.fill();

    let chart = canvas.add_image(ImageData::png(&std::fs::read("chart.png")?)?);
    canvas.draw_image(chart, 72.0, 480.0, 320.0, 240.0);

    let pdf = Pdf {
        pages: vec![page],
        ..Pdf::default()
    };
    pdf.save("report.pdf")?;
    Ok(())
}

The CLI covers the common shapes as one-liners:

pdfboss create blank  -o blank.pdf --pages 3 --size letter
pdfboss create text   notes.txt -o notes.pdf --font times-roman --font-size 12
pdfboss create images scan1.png photo.jpg -o scans.pdf

And CommonMark+GFM composes straight into a themed, paginated PDF (headings, lists, tables, code blocks, clickable links and images), deterministically, from all three surfaces. A theme is a small CSS subset over element-type selectors, overlaid on the built-in default; the Helvetica, Times and Courier families are available, and characters outside them are replaced with ? and reported:

body { font-family: times; font-size: 10.5pt; color: #222; }
h1   { font-family: helvetica; font-size: 2.2em; color: #a33; }
code { font-family: courier; background-color: #eee; }
pre  { background-color: #eee; padding: 8pt; }

from pathlib import Path

import pdfboss

pdf = pdfboss.md.to_pdf(
    Path("notes.md").read_text(),
    theme=Path("theme.css").read_text(),   # CSS source text, not a path
    size="letter",
)
Path("notes.pdf").write_bytes(pdf)

pdfboss create md notes.md -o notes.pdf --theme theme.css --size letter

In Rust, pdfboss_markdown::to_pdf returns the composed Pdf value plus a report of anything sanitized, ready for save/to_bytes or further canvas work.

Benchmarks

Text and parsing

Against other Python PDF libraries over 40 real-world PDFs (pages/sec, higher is faster):

pdfboss is the fastest library measured on both operations, including against the C-backed PyMuPDF and the Rust-backed pdf_oxide: 7,477 pages/s extracting text against PyMuPDF's 414 (about 18×) and pdf_oxide's 273 (about 27×), and 403,000 pages/s opening + parsing against pdf_oxide's 177,000 (about 2.3×).

Extraction quality

On opendataloader-bench (the 200-PDF corpus PDF-to-Markdown engines use for their published comparisons), pdfboss reads the whole corpus in about a seventh of a second, about 3× faster than the fastest competing Markdown engine, with a mid-field reading-order score (NID, higher is better):

Rendering

A renderer that skips work looks fast, so every file is certified before the stopwatch starts: any page that reports dropped or approximated content excludes its file, and an ink-coverage gate across libraries catches work skipped silently. 38 of the 40 files (888 pages) certify:

pdfboss rasterizes the mixed corpus fastest, about 33% ahead of pdfium itself, with no C in it.

Scanned documents

Scans are the other half of the world's PDFs: one full-page bilevel image per page, JBIG2- or CCITT-coded, no text operators. A 544-page JBIG2 book (1994 × 2832 samples per page) rasterized to PNG at 1:1:

pdfboss is the fastest of the four, about 18% ahead of the C-backed renderers, and the only one of them with no C in it.

In the browser

pdfarena races pdfboss against hayro, pdf.js and PDFium on any PDF you drop in, with pdfboss and hayro compiled to WebAssembly. Each engine renders in its own web worker, the stopwatch wraps only the render call, and every challenger is pixel-diffed against pdf.js as the reference. Nothing gets uploaded; the whole benchmark runs in your browser.

What's inside

Fourteen crates, one implementation: a from-scratch core with its own JPEG 2000, JBIG2, CCITT and ICC codecs, an anti-aliased rasterizer, layout analysis to plain text and Markdown, a deterministic PDF writer with CSS-themed Markdown composition, async range-fetching I/O, a CLI and TUI, and PyO3 bindings.

Limitations

Rendering is lenient and it says so: content pdfboss cannot read is skipped so the rest of the page still rasterizes, and every dropped or approximated item lands in a report. pdfboss render warns on stderr, the TUI raises a notice, and the libraries return it through render_page_reporting (Rust) and Page.render_reporting() (Python). The whole not-yet-supported list is two faces: /Symbol and /ZapfDingbats have no license-clean substitute, so they stay blank rather than borrowing an unrelated face's glyphs.

Documentation

The pdfboss book covers installation, guides for every surface (text, Markdown, styled spans, rendering, image extraction, creation, Markdown-to-PDF composition, async and remote documents, the explorer, encryption) and CLI/Python/Rust reference chapters. It is built with mdBook from docs/ by the book workflow and served at pdfboss.dev/docs. Per-crate Rust API documentation is on docs.rs.

Development

cargo test --workspace          # Rust test suite
cargo clippy --workspace --all-targets -- -D warnings
maturin develop                 # build the Python extension into your venv
pytest                          # Python integration tests
mdbook serve docs               # live-preview the documentation book

License

Dual-licensed under either of

• MIT license (LICENSE-MIT)
• Apache License, Version 2.0 (LICENSE-APACHE)

at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be dual-licensed as above, without any additional terms or conditions.