docling vs markitdown: a layout model pipeline against a thin Markdown converter

What each one is trying to produce

docling is a conversion pipeline built around models. Its README describes a tool that simplifies document processing by parsing diverse formats, including advanced PDF understanding, and providing integrations with the generative AI ecosystem. The PDF understanding is itemised: page layout, reading order, table structure, code, formulas and image classification. Underneath is a single representation, the DoclingDocument, and everything else is an export from it: Markdown, HTML, WebVTT, DocLang, DocTags and lossless JSON. It also parses application-specific XML schemas, naming DocLang, USPTO patents, JATS articles and XBRL financial reports, and it understands charts, converting bar charts, pie charts and line plots into tables or code with descriptions. The project's own framing is a document that is ready for generative AI, and the mechanism is to model the page and then serialise it.

markitdown is a converter with a narrow promise. Its README calls it a lightweight Python utility for converting various files to Markdown for use with LLMs and related text analysis pipelines, says it is most comparable to textract but with a focus on preserving important document structure and content as Markdown, including headings, lists, tables and links, and then states the limit of that promise in the same paragraph: the output is often reasonably presentable and human-friendly, it is meant to be consumed by text analysis tools, and it may not be the best option for high-fidelity document conversions for human consumption. Its reason for choosing Markdown is given too: it is close to plain text, models such as GPT-4o speak it natively, and its conventions are token-efficient.

That is the whole difference in one line. docling builds a model of the page and lets you export several views of it; markitdown reads a file and writes Markdown, and tells you the Markdown is for a pipeline rather than for a reader.

Install shapes and what ends up in the image

docling installs with pip install docling, requires Python 3.10 or higher because support for Python 3.9 was dropped in version 2.70.0, and the README states that it works on macOS, Linux and Windows for both x86_64 and arm64. The weight is not in the command line. The layout understanding means models are loaded to do the work, the README names GraniteDocling and other visual language models as options selectable with the CLI, and OCR for scans is built in. Our analysis puts the resource question first: Docling is the right tool when conversion must run on your own machine, and that is also the reason to check your hardware before anything else, and to skip it if you cannot give the process enough memory for the layout models.

markitdown asks for Python 3.10 or higher too, and its README recommends a virtual environment to avoid dependency conflicts, with commands for venv, uv and conda. Installation is pip install 'markitdown[all]', and the granularity is the point: the optional dependency sets are [pptx], [docx], [xlsx], [xls], [pdf], [outlook], [az-doc-intel], [az-content-understanding], [audio-transcription] and [youtube-transcription], so pip install 'markitdown[pdf, docx, pptx]' installs only what those three formats need. Nothing arrives that you did not ask for.

The operational comparison follows. docling gives you a self-contained converter whose cost is memory and model weights, and our analysis asks you to work out which of those weights your environment may legally redistribute if you ship a container, which is a question about licences and not about Python. markitdown gives you a package whose cost is a longer list of extras, and the shape of a service that installs a different extra set per worker.

Scans, images and where the text comes from

This is where the two part company most clearly.

docling lists extensive OCR support for scanned PDFs and images as a feature, not as a plugin, and the model set is pluggable through the CLI, where docling --pipeline vlm --vlm-model granite_docling points a run at a specific visual language model. A scan is therefore an input the default pipeline is meant to handle, and our analysis names scanned PDFs with layout, reading order and tables as the case it fits best.

markitdown's support for images is EXIF metadata and OCR, and for audio it is EXIF metadata and speech transcription. The OCR that reaches text inside a document comes from a plugin, and the markitdown-ocr plugin does it a particular way: it extracts text from embedded images using LLM Vision, through the same llm_client and llm_model pattern MarkItDown already uses for image descriptions, and it adds no new ML libraries or binary dependencies. The catch is in the README: if no llm_client is provided the plugin still loads, but OCR is silently skipped and the standard built-in converter is used instead. A silent fallback is a design choice for a plugin and a trap in a batch job, because the output looks like a successful conversion with the embedded text missing.

There is also a hosted route in markitdown's extras, with [az-doc-intel] and [az-content-understanding], and the README describes Azure Content Understanding as providing higher-quality conversion with structured field extraction in YAML front matter, multi-modal support and configurable analyzers. That is a different product category from a local converter, and it is worth knowing which side of the line a given requirement sits on.

Output formats and the agent stack

If the destination is a model, markitdown's output is exactly what it promises: Markdown with headings, lists, tables and links, returned as text_content from a convert call, or written to a file with markitdown path-to-file.pdf -o document.md. You can also pipe content, and the README notes that plugins are disabled by default, listed with markitdown --list-plugins and enabled with --use-plugins, with available plugins found by searching GitHub for #markitdown-plugin.

docling's output is wider. The same parsed document can be exported as Markdown, HTML, WebVTT, DocLang, DocTags or lossless JSON, and the DocTags format is a separate published format with its own paper. That matters when the next stage is not a language model but a renderer, an index, or another tool that needs the geometry back. The CLI writes a .md file into the current directory, and the Python path is a DocumentConverter whose result carries export_to_markdown().

The integration story tilts the same way. docling documents native integrations with LangChain, LlamaIndex, Crew AI and Haystack, plus an MCP server so an agent can reach it, and docling-serve to run it as a service with an API server. markitdown's documented surface is a CLI, a Python class, plugins, and those Azure extras. If your plan is an agent that fetches a document, parses it and continues working, docling is the project that describes that path; if your plan is a preprocessing step in front of a text pipeline, markitdown is enough and adds less to reason about.

Where docling falls short

The resource requirement is the first limit, and our analysis states it as a reason to skip: if you cannot give the process enough memory for the layout models, this is the wrong tool. That is not a tuning detail, it is a property of a design that models the page rather than reading its text stream.

The second limit is that it is more than most jobs need. Our analysis says to skip it if you only need plain text extraction from clean, text-layer PDFs, because a smaller extractor costs less to install and run. A clean digital PDF has a text layer, a text layer needs no layout model, and paying for a model pipeline to read it is cost without benefit.

Third, the surface is wide enough to be a liability in review. The format list covers PDF, DOCX, PPTX, XLSX, HTML, EPUB, Apple Pages in both the IWA container and the iWork '09 form, WAV, MP3, WebVTT, Box Notes, EML, MSG, PNG, TIFF, JPEG, LaTeX, DocLang, plain text, Markdown supersets, ODF, XBRL and video with an ASR transcript and keyframes. Every one of those is a parser to trust, a dependency to install, and a path where output can differ from what you expected on one file.

Fourth, output lands where the tool decides. The CLI generates a .md file in the current directory, which our analysis flags as one of the three things to verify, alongside how the default pipeline handles your worst scan and which weights you may redistribute. A converter that writes to the working directory is a small thing to notice in development and an annoying thing in a scheduler.

Where markitdown falls short

The project states its own ceiling: it is meant to be consumed by text analysis tools and may not be the best option for high-fidelity conversion for human consumption. Any requirement that a person reads the output, or that a downstream system needs layout back, is outside what it offers.

Second, the OCR story is conditional. Image support is EXIF metadata and OCR, and the text inside embedded images depends on a plugin, an llm_client and an llm_model. When the client is missing, the plugin loads anyway and OCR is silently skipped. There is also a network and licence dimension: the plugin uses LLM Vision through an OpenAI-compatible client, and the extras include Azure Document Intelligence and Azure Content Understanding, so a requirement for local-only processing is not automatic here.

Third, it is pre-1.0. The release line is v0.1.5 on 2026-02-20, v0.1.6 on 2026-05-26 and v0.1.7 on 2026-07-29, with the last recorded push on 2026-09-21. A 0.x line with multi-month gaps between releases means the entry points can move, and the project itself points you at a narrow choice of convert function, which is a sign of an API still being shaped.

Fourth, there is the security note, and it is the clearest statement in either README. MarkItDown performs I/O with the privileges of the current process, behaving like open() or requests.get(), it will access resources the process itself can access, and the README tells you to sanitise your inputs in untrusted environments and to call the narrowest convert function needed, for example convert_stream() or convert_local(). Our analysis draws the same line: do not adopt it if you must process untrusted uploads without sandboxing. That is a design constraint of a convenience tool, not a bug, and it is yours to contain.

Licence, maintenance and the choice for concrete situations

The licences are identical. docling is MIT and markitdown is MIT, so no choice between them turns on terms, and both are usable in a commercial product without a discussion. If a policy excludes copyleft, neither is affected.

Maintenance is the next axis, and it separates them by stage rather than by health. docling's last recorded push is 2026-09-29 and its releases cluster tightly, v2.122.0 on 2026-08-25, v2.123.0 on 2026-08-26 and v2.123.1 on 2026-08-28, which is the pattern of a project shipping many changes. markitdown's last recorded push is 2026-09-21 with v0.1.7 as the newest release on 2026-07-29, so the code is being worked on while the published line stays on 0.1.x. Neither repository is archived.

The situations below are clear.

A scanned contract archive where reading order and tables decide whether the extraction is usable. docling, because OCR for scans, page layout and table structure are in the default path rather than in a plugin.

An agent that has to fetch, parse and continue, wired to LangChain, LlamaIndex, Crew AI, Haystack or an MCP server. docling, because those integrations and docling-serve are part of what it is built for.

Documents that must stay inside your network, including air-gapped environments. docling, which lists local execution for sensitive data as a feature, and which does not require a client to be handed to it.

A text pipeline in front of a language model over files you control. markitdown, because Markdown with headings, lists, tables and links is the deliverable and the install is one extra per format.

A converter you will hand untrusted uploads. Neither without work, and if the choice is between them, markitdown tells you plainly that it performs I/O with the privileges of the current process, which means sandboxing is your responsibility and the narrowest convert function is the one to call.

A one-off PDF where the content is a clean text layer. Neither. Our analysis says a smaller extractor is the cheaper answer there.

Before committing, do what our analysis prescribes for each. For docling, check how the default pipeline handles your worst scan, whether the CLI output lands where your pipeline expects it, and which model weights your environment can legally redistribute if you ship a container. For markitdown, verify that the optional extras for your formats install on your platform, that the output structure of your specific documents survives conversion, and which convert entry point your code path actually calls.

Bottom line

docling is the right choice when the page has to be understood, because layout, reading order, tables, code, formulas and OCR are modelled before anything is exported, and markitdown is the right choice when a file has to become text for a pipeline, because it does that in one dependency-light step and tells you where its own limits are. Both are MIT, so terms never decide this, and the real dividing line is whether your input has a text layer. Verify first that docling's default pipeline handles your worst scan, that you can give the layout models the memory they need, and which weights you may redistribute, and for markitdown that your formats' extras install, that your document structure survives conversion, and whether your OCR path silently falls back when no llm_client is present. The judgement to take away is that this is not a quality contest, since a thinner tool is the correct tool when the output is only ever read by a model, so decide by whether the page must be reconstructed or merely transcribed.

Sources

1. docling-project/docling repository
2. docling-project/docling README
3. microsoft/markitdown repository
4. microsoft/markitdown README