Choosing a Parser

This guide helps you pick a parser and install the right extra. The default is Docling, the best all-round local choice; the other options trade off file-type coverage, install size, and output quality.

The Parser slot is stage 02 of the pipeline. It turns each file into a normalized ParsedDoc — holding text, structural blocks, tables, and image refs — that every later stage consumes.

indx composes parsers rather than replacing them, so the choice comes down to matching your corpus and constraints to the strengths of each backend.

The options at a glance

Every parser implements the same Parser protocol (parse(path) -> ParsedDoc). The pipeline never knows which one is active, so you can switch freely without touching anything downstream.

Parser	Strengths	Best for	Local?	Extra
Docling (default)	High-fidelity layout, reading order, tables, and figures from PDF/Office docs; richest structured output of the local options; permissive (Apache-friendly) license.	The default, offline, document-heavy knowledge spaces.	Yes	indx[docling]
Unstructured	Very broad file-type coverage and a mature partitioning ecosystem.	Heterogeneous corpora with many odd/long-tail formats.	Yes	indx[unstructured]
LlamaParse	Excellent on complex/messy PDFs via a hosted service.	Hard documents where cloud quality is worth it.	No (cloud)	indx[llamaparse]
MarkItDown	Lightweight, fast Markdown conversion with minimal dependencies.	Quick/simple conversions and the lightest local install.	Yes	indx[markitdown]
plaintext	Zero-dependency fallback that ships in core; reads text as-is.	Air-gapped runs, plain-text/Markdown corpora, CI smoke tests.	Yes	none (in core)

The plaintext floor

The plaintext parser ships inside core, alongside the jsonl store and .indx/jsonl writers. This means pip install indx with no extras can complete a full build offline. It does no layout extraction, but it guarantees indx always has a working parser.

How to select a parser

The parser slot is resolved with the same precedence as every other component:

explicit code argument / use()   >   CLI flag   >   indx.toml   >   documented default

On the CLI

Use --parser to override per run:

# Default (Docling) — requires indx[docling]
indx ./docs --out ./ai-ready

# Lightest local parser
indx ./docs --out ./ai-ready --parser markitdown

# Broad format coverage
indx ./docs --out ./ai-ready --parser unstructured

In indx.toml

The parser lives under the [parser] section, keyed engine:

[parser]
engine = "docling"   # docling | unstructured | llamaparse | markitdown | plaintext

See the full configuration reference for the complete key table and precedence rules.

As a Parser object (SDK)

For a fully custom or pre-configured parser, pass an instance to the DirectoryPipeline. You can do this at construction or via use():

from indx import DirectoryPipeline

# By name
pipeline = DirectoryPipeline(parser="markitdown")

# By object (anything satisfying the Parser protocol)
from my_pkg import MyMarkdownParser
pipeline = DirectoryPipeline().use(parser=MyMarkdownParser())

space = pipeline.run("./docs", "./ai-ready")

Writing your own parser is covered in Bring-your-own components.

Install the matching extra

Parsers are optional extras, so the core install stays small. Each backend pulls its own heavy dependencies:

Install	Enables
pip install indx[docling]	DoclingParser (default)
pip install indx[unstructured]	UnstructuredParser
pip install indx[llamaparse]	LlamaParseParser
pip install indx[markitdown]	MarkItDownParser
pip install indx[local]	The full local profile (docling + ollama + bge-m3 + qdrant), the opt-in offline stack

The plaintext parser needs no extra — it is always available.

MissingDependencyError is actionable

If you select a parser whose extra is not installed, indx raises a single, clear error naming the exact command to run. For example:

MissingDependencyError: parser 'docling' requires the 'docling' extra: pip install indx[docling]

The error appears only when that slot is actually selected. An installed-but-unused backend never affects an unrelated run. For the light path, the message points you at pip install indx[markitdown] instead.

Choosing against the four constraints

indx is designed around four product principles. Each parser trades against them differently.

Local-first / air-gapped

Docling, Unstructured, MarkItDown, and plaintext all run fully local with no network calls.

LlamaParse is the exception: it is cloud-only. It sends documents to a hosted service and needs an API key, which breaks the local profile. Reach for it only when cloud quality on genuinely hard PDFs is worth crossing that line. See Local & air-gapped.

Light core

pip install indx carries no parser beyond the in-core plaintext fallback.

Among the optional parsers, MarkItDown is the lightest, with minimal deps and fast Markdown conversion — the recommended choice when install size matters most. Docling is the heaviest local option, since on some configurations it pulls models and Torch, which is why it ships as an extra rather than in core.

No lock-in

Every parser sits behind the same Parser protocol. A third party can publish a new one, advertised via the indx.parsers entry point, that works by name with no fork of indx.

Swapping parsers is always a config change, never a rewrite. See authoring a plugin.

Output quality for downstream stages

Chunk, Relate, and Enrich are only as good as the structure the parser preserves.

Docling produces the richest structured output of the local options — reading order, tables, and figures — and generally yields the best chunking and relating. MarkItDown is local and light but loses structure Docling keeps, and plaintext keeps none at all.

Quick decision guide

Rules of thumb

• Default / document-heavy & offline → Docling (indx[docling]).
• Lightest local install, simple/Markdown content → MarkItDown (indx[markitdown]).
• Many odd or long-tail file formats → Unstructured (indx[unstructured]).
• Hard, messy PDFs and cloud is acceptable → LlamaParse (indx[llamaparse]).
• Strictly air-gapped, zero extras, plain text → plaintext (in core).

Related pages

• Component protocols — the Parser contract in full.
• Bring-your-own components — write and plug in your own parser.
• Extras reference — the complete optional-dependency matrix.
• Choosing a store and choosing an embedder — the same decision framework for the other slots.