MarkItDown

Why it's ranked here

Nearly every document ingestion pipeline needs something unglamorous sitting in front of it, and this fills that slot under an MIT license with a Microsoft copyright. The base install is light, six runtime dependencies, with every format library behind an optional extra, and the XML-hardening dependency sits in the base set rather than behind an extra. Maintenance signals are structural rather than promotional: type checking configured, test directories in all four packages, a pre-commit setup checked in. Shipping as a library, a CLI and an MCP server means it fits pipelines that were not designed around it.

What's good

The extension point is small and precisely documented: a converter implements exactly two methods, and the written contract spells out the non-obvious rule that a handler which peeks at bytes must rewind the stream before returning. Optional formats fail helpfully: an unconfigured format raises a message naming the exact extra to install instead of breaking at import time. The HTML path catches a recursion failure in its Markdown generator and falls back to an iterative text extraction. The bundled MCP server binds only to the local machine by default and prints an explicit warning that it has no authentication when told to listen elsewhere.

Tradeoffs

Output fidelity is bounded by whatever library sits underneath, and the project's own documentation says plainly it may not be the best option for high-fidelity conversion meant for human reading. The image handler accepts only JPEG and PNG, and without a configured language model it emits nothing but photo metadata; that captioning routine also exists twice in the codebase. PDF form and table detection is a stack of positional heuristics with hard-coded tuning values whose behavior is hard to predict on an unfamiliar document. Plugin loading failures become warnings rather than errors, and the main class is still described as in preview.

How to use it well

Install only the format extras you need rather than everything, which pulls in fifteen further packages on top of the six base dependencies, including three Azure SDKs. Follow the project's security note and call the narrowest entry point, because a plain string that looks like a URL gets fetched with the current process's privileges. When feeding data through standard input, pass the extension, media-type or character-set hints so detection is not left entirely to content sniffing. Leave plugins off unless you need one; they are opt-in. If you route work to Azure Content Understanding, restrict which file types go there, since every routed conversion is a billable call.

Observed

License

MIT, Copyright Microsoft Corporation

Interfaces

Command-line tool, importable Python library, and a separate MCP server package

Packaging

Six base runtime dependencies; every format library sits behind an optional extra

MCP server default binding

Local machine only, with a printed warning that the server has no authentication on other interfaces

Tests

Per-package test directories present in the repository tree for all four packages