hayro is a pure Rust PDF renderer split into nine crates

A renderer that admits what it does not do

hayro is described as an experimental, work in progress PDF interpreter and renderer. The task it sets itself is to interpret one or many pages of a PDF file, for example to convert them into PNG or SVG files.

The README is unusually direct about the difficulty. The PDF specification is huge and contains many features, and there are millions of PDF files out there with many edge cases, so a solid renderer has to handle those as well as possible. It also notes this is not the first attempt at writing a PDF renderer in Rust, and claims, to the best of the author's knowledge, to be the most feature complete library of the kind currently.

Two features are named as unsupported: rendering knockout groups, and PDFs with non embedded CID fonts. The claim that follows is that the vast majority of common features is supported, so an average PDF should render without issues.

That claim has a specific underpinning. The README says hayro handles the 1400 or more PDFs in the test suite, which to a large part have been scraped from the PDFBOX and pdf.js test regression suites. Reusing two independent projects' regression corpora is the strongest evidence in the document, and it is also the reason the edge case list is short rather than empty.

The crate is published on crates.io as hayro, and the licence is Apache-2.0 OR MIT.

Nine crates, one for each layer of the pipeline

The project is not a single crate. The README says it encompasses a number of different crates which can in theory be used independently, and lists them.

hayro-syntax does low level parsing and reading of PDF files. hayro-interpret is a PDF interpreter that emits commands into an abstract Device, which is the key design idea: the interpreter does not know about pixels, it emits drawing commands, and a Device consumes them. hayro itself renders PDF pages into bitmaps, and hayro-svg converts PDF pages into SVG images.

Then there are the format specific pieces. hayro-jpeg2000 is a JPEG2000 image decoder, hayro-jbig2 is a JBIG2 image decoder, and hayro-ccitt decodes group 3 and group 4 CCITT encoded images. hayro-postscript is a lightweight scanner for a specific subset of PostScript, and hayro-cmap parses CMap files in PDFs.

The Device abstraction is what makes the split pay off. A renderer that emits into an abstract device can have a bitmap target and an SVG target without either of them knowing about the other, and the same interpreter can be reused by anything that wants a device.

The workspace in the repository root matches that list, with a member per crate plus the extras: hayro-bench for benchmarks, hayro-demo, hayro-tests, hayro-fuzz for fuzzing, and hayro-write for writing PDFs, which is not listed in the README's crate summary but exists in the manifest and the tree.

Depending on one crate or the whole workspace

The workspace manifest shows how the crates relate, and it is the clearest description of the dependency structure available. Each crate is a path dependency with a published version and default features switched off:

hayro = { path = "hayro", version = "0.8.0", default-features = false }
hayro-ccitt = { path = "hayro-ccitt", version = "0.4.0", default-features = false }
hayro-interpret = { path = "hayro-interpret", version = "0.8.0", default-features = false }
hayro-jpeg2000 = { path = "hayro-jpeg2000", version = "0.4.1", default-features = false }
hayro-jbig2 = { path = "hayro-jbig2", version = "0.3.1", default-features = false }
hayro-syntax = { path = "hayro-syntax", version = "0.8.0", default-features = false }
hayro-svg = { path = "hayro-svg", version = "0.8.0", default-features = false }

The core crates sit at 0.8.0 while the format decoders are younger, with hayro-ccitt at 0.4.0, hayro-jpeg2000 at 0.4.1 and hayro-jbig2 at 0.3.1, and the two newest ones, hayro-postscript and hayro-cmap, at 0.1.0.

The version spread is informative on its own. A crate at 0.1.0 is a new API, and a 0.8.0 crate in a 0.x line has probably churned a few times. The default-features-off pattern on every internal dependency also means the top level crate decides which codecs get compiled in, which is how you avoid pulling in a JBIG2 decoder you never need.

The workspace itself is edition 2024 with a rust-version of 1.92, and the author notes in a comment that the CI configuration has to be changed alongside it.

The demo is a viewer only in the loosest sense

There is a demo tool at laurenzv.github.io/hayro/, and the README is careful about what it is. It calls it a quick, vibe-coded PDF viewer not intended to be used as an actual viewer, and lists what is not implemented there and out of scope: text selection, search, annotations and forms.

It is meant as a quick way to test the rendering capabilities and performance of hayro. That is an important caveat, because a browser PDF viewer is the thing most people picture, and this is not that. What it is is a page rasteriser you can look at.

The features that are absent are the features a PDF library needs most for real work. Text selection means the glyph positions have to be recoverable rather than just drawn, search means the text has to be extracted as text rather than as shapes, annotations and forms are interactive content that a renderer has to model rather than paint. A library that paints well and cannot read is still useful for the job of producing images, and useless for the job of editing a document.

The demo is best read as a benchmark harness with a window, since performance is exactly what the README says has not been a focus.

Performance is the acknowledged weak spot

The README states the limitation directly. The crate is still in a very development stage and there are issues that remain to be addressed, most notably performance, which has not been a focus at all so far but will become a priority in the near future.

That sentence is doing a lot of work, because a PDF renderer that is slow is a PDF renderer nobody uses in a request path. The two things a PDF library competes on are fidelity and speed, and hayro currently leads on the first by the measure of the 1400 file test suite and lags on the second by its own admission.

The repository has a hayro-bench crate and a hayro-demo, and the demo's stated purpose includes testing performance, so the means to measure exist even if the result is not yet good. The rendering stack also suggests where the cost sits: resvg at 0.47.0 for SVG rasterisation, moxcms for colour management, skrifa for font handling, kurbo for paths and flate2 for the compressed streams that most PDFs are built from.

Anyone evaluating hayro for a server side conversion service should benchmark their own documents. The enwik8 style headline numbers people cite for other tools say nothing about a PDF renderer, and the corpus that matters is the PDFs your users actually upload.

Tooling around the crates: fuzzing, benchmarks and writing

The workspace members list includes hayro-fuzz, hayro-write and hayro-bench, and the tree has a scripts directory and an assets directory.

A fuzzing crate matters more for a PDF library than for most projects, because a PDF parser reads hostile input. Every real PDF library in the wild has had security advisories, and the only defence that has ever worked is throwing malformed files at the parser in a loop and fixing what falls over. hayro-fuzz is the container for that work.

hayro-write is the reverse direction, writing PDFs rather than reading them, which is unusual to find in a renderer crate. It is worth knowing it exists if your use case involves generating a PDF from the same intermediate representation the interpreter uses, because the shared representation is the interesting part of the design.

The repository is not archived and the last push was on 2026-10-19, so the code is being worked on daily. The repository has no GitHub releases, so the crates.io versions are the reference points, and the workspace manifest carries a NOTICE.md alongside the two licence files, which is what the Apache-2.0 side of the dual licence asks for.

Editorial conclusion

hayro suits a Rust project that needs to turn PDF pages into images without a native dependency or a headless browser, and the crate split lets you take only the layer you need. It is the wrong choice if you need a viewer with text selection, search, annotations or forms, since the demo explicitly leaves those out of scope, and you should not expect production rendering speed yet. Before depending on it, check the MSRV of 1.92 against your toolchain, run it over the kind of PDFs your users actually upload, and confirm the missing features, such as knockout groups and non embedded CID fonts, do not appear in your documents.

Frequently asked questions

Official sources

1. Issues
2. LaurenzV/hayro on GitHub
3. License: Apache-2.0
4. README