Chunkr: Self-Hosted Document Parsing for RAG Pipelines
Vision infrastructure to turn complex documents into RAG/LLM-ready data
At a glance
- What is it?
- Chunkr is an AGPL-3.0 document intelligence service in Rust that turns PDFs, slides, Word files and images into layout-aware chunks. The open source build runs community models and is positioned by its own README as a development and testing tool rather than a production replacement for the hosted API.
- Who is it for?
- Adopt the open source build if you need to read the pipeline, host parsing inside your own network, or evaluate chunk quality before committing to a vendor. Do not adopt it expecting parity with chunkr.ai: the README states the cloud API runs proprietary in-house models, and the feature table marks Excel support as absent from the open source repo.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 6 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Gap Chunkr Fills Between Raw Text Extraction and Usable Chunks
Most PDF-to-text tools return a stream of characters with no notion of where anything sat on the page. That is enough for keyword search and close to useless for retrieval augmented generation, where a chunk that merges a table header with the paragraph below it poisons the embedding. Chunkr targets exactly that middle layer. The README describes it as a production-ready service for document layout analysis, OCR, and semantic chunking, converting PDFs, PPTs, Word docs and images into RAG/LLM-ready chunks.
The intended user is an engineer building a retrieval pipeline who has already decided that naive text extraction is not good enough. The repository is written in Rust, ships as a set of services, and exposes both a web UI and an HTTP API. It is not a library you import into an existing Python script. You run it, then call it. That distinction matters for anyone comparing it against a parsing function inside their own application.
The README is also explicit that the open source release and the hosted product are different artifacts. The open source version uses community and open source models, while the cloud API runs proprietary in-house models. Anyone evaluating the repository is therefore evaluating a pipeline and an interface, not the accuracy numbers of the commercial product.
Layout Analysis, OCR and VLM Processing Inside the Pipeline
The README lists four capabilities in sequence: layout analysis, OCR with bounding boxes, structured HTML and Markdown output, and vision-language model processing. Read together, they describe a flow. A document arrives, layout analysis segments it into regions, OCR extracts text from those regions while preserving coordinates, a vision-language model handles the parts that plain OCR handles poorly, and the result is emitted as structured HTML or Markdown.
The bounding box detail is the part worth pausing on. Coordinates let a downstream system reconstruct reading order, crop a figure, or attach a citation back to a page region. Chunkr does not appear to throw that information away when it produces Markdown, which is what makes the output auditable rather than just convenient.
The vision-language model step is configurable, and that is where the architecture becomes concrete. Chunkr does not bundle a model. It expects you to point it at an OpenAI-compatible chat completions endpoint, either through a models.yaml file or through three environment variables. The models.yaml example in the README shows a provider_url such as https://api.openai.com/v1/chat/completions alongside an api_key, a default flag, and an optional rate-limit expressed in requests per minute. So the heavy semantic work is delegated to whatever endpoint you supply, while the layout and OCR stages run inside the deployment.
Starting Chunkr with Docker Compose on GPU, CPU and Mac ARM
The documented path is Docker Compose. You clone the repository, copy .env.example to .env, and copy models.example.yaml to models.yaml. Then you pick a compose invocation depending on hardware. The plain docker compose up -d is the GPU deployment. For CPU-only machines the README gives docker compose -f compose.yaml -f compose.cpu.yaml up -d. For Mac ARM architectures (M1, M2, M3 and later) it adds a third overlay: docker compose -f compose.yaml -f compose.cpu.yaml -f compose.mac.yaml up -d.
Once running, the web UI answers on http://localhost:5173 and the API on http://localhost:8000. Shutdown mirrors the startup command with down in place of up -d, and the same file overlays apply.
Configuration for the language model has two routes. The recommended one is models.yaml, which the README says supports multiple providers at once, default and fallback models, and distributed rate limits per model, with models referenced by ID in API requests. The basic route is three environment variables in .env: LLM__KEY, LLM__MODEL and LLM__URL. The double underscore is the nesting separator, and the README states any OpenAI API compatible endpoint works. If you only need one model, the environment variables are fewer moving parts. If you need a fallback when a provider rate-limits you, the YAML file is the only one of the two that documents that capability.
Excel Is Absent and the Open Source Build Is Not the Hosted Product
The README's own comparison table marks Excel support with a cross for the open source repo and a check for both the cloud API and the enterprise edition, described there as a native parser. If your corpus includes spreadsheets, this repository does not cover it. The stated document types for the open source build are PDF, PPT, Word and images.
The second limitation is accuracy, and it is stated by the project rather than inferred. The cloud API runs proprietary in-house models for what the README calls higher accuracy, speed, and enterprise reliability, while the open source release uses community and open source models. The comparison table repeats this across layout analysis, OCR and VLM processing. There is no published figure in the supplied material quantifying the gap, so treat any assumption about how close the community models come as unverified.
The third constraint is hardware. Two of the three documented compose paths are CPU paths, which suggests the pipeline can run without a GPU, but the README also lists the NVIDIA Container Toolkit as a prerequisite for GPU support and does not state minimum VRAM, throughput, or memory requirements anywhere in the material provided. Capacity planning has to be done empirically on your own documents.
Where Chunkr Sits Against Unstructured and Plain PyMuPDF Extraction
The obvious comparison is Unstructured, which also converts PDFs and office documents into structured elements with layout awareness and can be self-hosted. The difference is packaging and language. Unstructured is a Python library and a set of services you typically call from inside a Python ingestion job, so the parsing logic lives in the same process as your pipeline code. Chunkr is a Rust service with its own API and web UI, so parsing happens behind an HTTP boundary. That boundary is convenient when several applications need the same parsing behaviour, and inconvenient when you want to call the parser as a function inside a loop you are already debugging.
The second comparison is against doing the work yourself with a text extractor plus a chunking library. That approach is cheaper to start and has no service to operate. It also gives you no bounding boxes and no vision-language model pass, which is precisely the layer Chunkr adds. The decision is less about whether Chunkr parses better than a free library and more about whether you need region coordinates and VLM handling badly enough to run and maintain a service.
A third point of comparison is the vendor's own cloud API. The README frames the split openly: the open source repo is for development and testing, the cloud API for production workloads, and the enterprise edition for large-scale or high-security deployments with on-prem or VPC options. That is an unusually candid positioning statement, and it should be read as the project telling you where it expects the open source build to be used.
AGPL-3.0, Upgrade Cadence and the Cost of Running Your Own Parser
Chunkr is licensed AGPL-3.0. That is a copyleft licence with a network clause, and it applies to the whole repository. If you modify Chunkr and offer it to users over a network, the licence's obligations attach to your modified version. The supplied material does not include the full licence text or any additional terms, so read the LICENSE file in the repository and, if the distinction matters to your business, take advice rather than relying on a summary. Nothing here is legal advice.
The release history shows version v2.2.1 on 2025-07-31 and v2.2.0 the day before, with a separate tag for chunkr-services at v0.1.6 on the same date. The presence of a versioned services artifact alongside the main application version suggests the service layer can move independently, which is worth knowing when you pin versions for a deployment. The repository is not archived and shows activity through September 2026.
Operational cost is the part the README does not address. You are running Docker Compose with a web UI, an API, and OCR and layout models, and you are paying for whatever LLM endpoint you configure. The models.yaml rate-limit field exists precisely because that endpoint can throttle you. Upgrades mean re-pulling images and re-checking your models.yaml against models.example.yaml, since the README treats the example file as the reference for available options. There is no documented migration guide in the supplied material.
Who Should Run Chunkr and What to Confirm First
Run the open source build if document parsing has to happen inside your own network, if you want to inspect how layout and OCR feed into chunking before trusting a vendor, or if you are prototyping a RAG pipeline and want an API-shaped parser rather than a Python dependency. The Docker Compose path is short, the LLM configuration is a single YAML file or three environment variables, and the output includes the bounding boxes that make citations possible.
Do not run it if your documents include spreadsheets, since the README's own table excludes Excel from the open source repo. Do not run it if you need the accuracy the vendor advertises for its hosted models, because the README states those are proprietary and not in this repository. And do not run it if you cannot operate a stateful service, because this is not a library you import.
The first things to verify are concrete. Confirm your LLM provider exposes an OpenAI-compatible chat completions endpoint, because both configuration paths assume it. Decide between models.yaml and the LLM__KEY, LLM__MODEL and LLM__URL variables before you write deployment automation, since only the YAML route documents fallback models and per-model rate limits. Pick the correct compose overlay for your hardware, remembering that Mac ARM needs compose.yaml, compose.cpu.yaml and compose.mac.yaml together. Then read the LICENSE file and the models.example.yaml comments, because those two files carry the terms and the options that the README only gestures at.
Editorial conclusion
Adopt the open source build if you need to read the pipeline, host parsing inside your own network, or evaluate chunk quality before committing to a vendor. Do not adopt it expecting parity with chunkr.ai: the README states the cloud API runs proprietary in-house models, and the feature table marks Excel support as absent from the open source repo. Before deploying, confirm that your LLM endpoint is OpenAI-compatible, check whether your hardware needs the CPU or GPU compose files, and read the AGPL-3.0 terms against how you intend to expose the service.
Community notes