# Ferrules, a Rust PDF parser aimed at documents built for language models

> Ferrules turns PDFs into structured, LLM-ready output using pdfium2 for text, Apple Vision for OCR and a tiered table engine, and it ships as a Rust workspace with a CLI, an API and a debug viewer. It is convincing on macOS and incomplete everywhere else.

**AmineDiro/ferrules** — Modern, fast, document parser written in  🦀

- Repository: https://github.com/AmineDiro/ferrules
- Stars: 615 · Forks: 15
- Language: C
- License: GPL-3.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/aminediro-ferrules

## Ferrules is a document parser, not a document converter

Ferrules is described as an opinionated high-performance document parsing library designed to generate LLM-ready documents. The distinction matters. A converter turns page one into text and stops. Ferrules is trying to produce a structured representation: page layouts, detected tables, grouped blocks, headings, lists, captions and footers, all serialized as HTML, Markdown or JSON so the result can be fed into a retrieval or prompting pipeline without a second parsing stage. The project names itself a library but ships four Rust crates in one cargo workspace. The workspace file lists ferrules-core, ferrules-cli, ferrules-api and ferrules-debug as members, so the parsing engine, a command line front end, a service binary and a visual inspector are separate deliverables built from the same core. A work in progress banner points at a ROADMAP.md for what comes next, and one feature on the list, configurable inference parameters, is marked as coming soon. That tells you the shape of the project: a working core with a thin and still growing surface around it.

## pdfium2 for text, Apple Vision for OCR, ort for the models

The pipeline is visible from the feature list and the repository layout. PDFs are read with pdfium2, so the text layer, the vector paths and the page geometry come from a PDF engine rather than from a hand-written parser. Where a page has no usable text layer, the macOS path uses Apple's Vision framework through objc2 Rust bindings and the VNRecognizeTextRequest, which makes OCR a platform dependency rather than a bundled model. Layout analysis and the machine learning parts run through the ort library, and onnxruntime is a runtime dependency, which shows up in the container build where the shared library is copied into the runtime image and ldconfig is run. The output merges the layout analysis with the native PDF text lines, so a result is not a flat text dump but a set of regions with their content attached. Models are addressed through a filesystem path supplied on the command line, and the repository carries models/ and font/ directories next to libs/ and infra/, which is what a model-backed parsing stack looks like on disk.

## Table extraction runs Lattice, then Stream, then Vision

Table handling is the part of the pipeline with the most specific description, and it is a cascade rather than a single model. Lattice comes first: it reads explicit borders from PDF vector paths and is described as the most accurate method for traditional ruled tables. When a table has no visible borders, Stream reconstructs the grid from text alignment and whitespace gaps. Vision, a deep learning fallback using the Table Transformer model, is invoked only when the earlier results look suspicious, and the example given is low cell density over a large area. The engine sequences this automatically, so a Stream result that looks incomplete or messy triggers Vision to verify and improve the structure. Spanning cells are handled and cell alignment preserved, which is where most rule-based table extractors lose information. The tradeoff is cost. Any table in a document can reach the deep learning path, and the layout model, the Table Transformer and the OCR engine all have to be present on the machine for that fallback to help rather than quietly degrade.

## Downloading the macOS binary and parsing a first PDF

Ferrules provides precompiled binaries for macOS, downloaded from the GitHub Releases page, and the documented route is a download followed by a version check to confirm the binary runs on your machine. Parsing a document then takes a single argument, the path to the PDF file, and the results are written into the current directory as a JSON file named after the input document.

```sh
ferrules path/to/your.pdf
```

The companion invocation names the file explicitly so the output name is predictable.

```sh
ferrules file.pdf
```

What you should see is a progress line that reports how long the document took to parse, followed by a note that the results were saved as a JSON file next to where you ran the command. The README notes that precompiled binaries are for macOS, and Linux support with NVIDIA GPU acceleration is described as available soon, so the release page is also where you check whether a binary for your platform exists.

## The .ferr archive and the ferrules-debug viewer

Debugging a parser is a different problem from debugging an application, and Ferrules treats the document pipeline as inspectable state. Passing the debug flag to the CLI produces visual JSON results and cropped images where enabled, plus a .ferr debug archive containing the intermediate states: layout, OCR, native lines and tables. The companion tool ferrules-debug is a cross-platform visualizer built with Iced, and it reads that archive directly.

```sh
ferrules path/to/your.pdf --debug
```

The workflow is to run the parser with the debug flag on a sample file, open the resulting .ferr file in the viewer, and toggle between the Layout, OCR, Tables and Blocks layers to see how the engine read the page. The repository ships examples/sample-tables.pdf, which is the obvious file to point this at while you learn what the tool is telling you. That layer toggle is the interesting part. It turns a wrong table into a question about which stage misread it, which is a much cheaper way to debug than re-running with different settings and guessing.

## Apple Silicon acceleration exists, Linux acceleration does not yet

The command line options expose four separate backends for the layout model and they are not equivalent. CoreML enables or disables Apple's CoreML path for layout inference. The use-ane flag turns on Apple Neural Engine acceleration and applies only when CoreML is enabled. Then there is a TensorRT flag and a CUDA flag, with a device-id option that takes a GPU index and defaults to zero, plus graph optimization control through the Ort graph optimization level. Threading is tunable too, with intra-threads for parallel work inside an operation defaulting to two and inter-threads for operations running in parallel defaulting to one. The obvious gap is platform coverage. Precompiled binaries are offered for macOS, and Linux support with NVIDIA GPU acceleration is described as available soon. The container route exists in the repository as a Dockerfile that builds ferrules-api on a Debian bookworm base and a separate Dockerfile.gpu, along with build-docker.sh and publish-docker.sh, so the source path for a Linux deployment is present even though the release binaries are not.

## Where Ferrules differs from a Python parsing stack

The comparison the project makes is with unstructured, which it describes as slow and Python based, in favour of a Rust implementation that deploys without a Python runtime. That difference is architectural rather than cosmetic. Ferrules ships a native binary and a service image whose runtime stage installs only openssl and ca-certificates, so a container serving parsed documents carries no interpreter, and the API crate is built directly by the Dockerfile with cargo build --release -p ferrules-api. The acceleration story follows from the same choice, since the model runtime is onnxruntime with CoreML, ANE, TensorRT and CUDA paths rather than a Python binding layer. Against that, the project is smaller and unfinished in ways that matter. It is not archived and its last push was on 2026-04-26, and the recent tags are v0.1.11 from 2026-02-18, v0.1.9 from 2026-02-16 and v0.1.8 from 2025-03-22, so the version numbers still sit well below one and the release history has gaps. Licence terms are GPL-3.0, which matters more for a service binary than for a library you link into a larger program.

## Conclusion

Ferrules fits a team that parses a large volume of PDFs on macOS and wants structured output without a Python runtime in the deployment path, and it fits a team that needs to see why a table was reconstructed a certain way, because the.ferr archive and the ferrules-debug viewer expose the intermediate states. It does not fit a Linux deployment today, since NVIDIA acceleration is described as coming soon, and the documented release downloads are macOS binaries. Before adopting it, parse one representative PDF with --debug and read the result, confirm the layout model path resolves on your machine, and check that the tiered table heuristics handled your bordered and borderless tables instead of sending every page to the Vision model.

## FAQ

### What is Ferrules and what does it produce from a PDF?

Ferrules is a Rust document parsing library that turns PDFs into LLM-ready documents. It renders results as HTML, Markdown and JSON, and the output includes page layouts, extracted tables, grouped blocks and detected headings.

### How do I install Ferrules and parse my first PDF?

Precompiled binaries are published for macOS on the GitHub Releases page, and the install can be verified with ferrules --version. Running ferrules path/to/your.pdf parses the document and writes the results into the current directory as a JSON file named after the input.

### How does Ferrules decide how to read a table?

It tries Lattice first, which detects explicit borders from PDF vector paths, then Stream, which reconstructs a grid from text alignment and whitespace gaps for borderless tables. A deep learning fallback using the Table Transformer model runs when the earlier results look suspicious, such as low cell density over a large area.

### Can Ferrules parse PDFs on Linux with an NVIDIA GPU?

Not from the published artifacts yet. Precompiled binaries are offered for macOS, and Linux support with NVIDIA GPU acceleration is described as available soon, although the repository contains a Dockerfile and a Dockerfile.gpu for building the ferrules-api service from source.

### What does the debug flag give me in Ferrules?

It produces visual JSON results and cropped images where enabled, plus a .ferr debug archive holding the intermediate states, meaning layout, OCR, native lines and tables. The ferrules-debug visualizer opens that archive and lets you toggle between the Layout, OCR, Tables and Blocks layers.

## Sources

- [AmineDiro/ferrules on GitHub](https://github.com/AmineDiro/ferrules)
- [Issues](https://github.com/AmineDiro/ferrules/issues)
- [License: GPL-3.0](https://github.com/AmineDiro/ferrules/blob/main/LICENSE)
- [README](https://github.com/AmineDiro/ferrules/blob/main/README.md)
- [Releases](https://github.com/AmineDiro/ferrules/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aminediro-ferrules