MarkItDown: LLM Document Conversion in Python
/markitdown
MarkItDown turns PDFs, Office files, images, and audio into Markdown that an LLM can actually parse, rather than raw binary or messy HTML. Reach for it when you're feeding documents into a RAG pipeline or an LLM context window and want headings, tables, and lists preserved as plain text. Skip it if you need pixel-perfect output for a human reader — the README itself says that's not the target.
Converting Documents to Markdown
MarkItDown is a Python utility from Microsoft that converts files — PDF, Word, PowerPoint, Excel, images, audio, HTML, ZIP archives, even YouTube URLs — into Markdown. It keeps headings, lists, tables, and links intact instead of flattening everything into plain text, so downstream code can still tell a table from a paragraph. The project describes itself as most comparable to textract, but aimed at machines, not a polished document.
Supported File Types and Conversion Options
- ✓Converts PDF, PowerPoint, Word, Excel, HTML, CSV/JSON/XML, ZIP archives, EPubs, and YouTube URLs to Markdown, plus images and audio via EXIF metadata and OCR/speech transcription
- ✓Command-line tool (`markitdown path-to-file.pdf > document.md`) and a Python API (`MarkItDown().convert()`)
- ✓Optional Azure Document Intelligence backend for cloud-based layout extraction
- ✓Optional Azure Content Understanding backend that adds structured field extraction (invoice amounts, dates) as YAML front matter, plus audio and video support
- ✓Third-party plugin system, off by default, enabled with `--use-plugins`; the official `markitdown-ocr` plugin adds LLM-Vision OCR to PDF, DOCX, PPTX, and XLSX
- ✓Optional LLM-generated image descriptions for PPTX and image files when you pass an `llm_client` and `llm_model`
Getting Started with MarkItDown
Requires Python 3.10 or newer. Install the full feature set with `pip install 'markitdown[all]'`, or a subset like `pip install 'markitdown[pdf,docx,pptx]'` to skip dependencies you don't need. From source: `git clone [email protected]:microsoft/markitdown.git`, `cd markitdown`, `pip install -e 'packages/markitdown[all]'`. A Dockerfile ships in the repo too (`docker build -t markitdown:latest .`).
Converting Files with MarkItDown
From the CLI: `markitdown path-to-file.pdf > document.md`, or `-o document.md` to name the output, or pipe input with `cat path-to-file.pdf | markitdown`. From Python: `from markitdown import MarkItDown; md = MarkItDown(); result = md.convert("test.xlsx"); print(result.text_content)`. Pass `docintel_endpoint` to route through Azure Document Intelligence, or `cu_endpoint` for Azure Content Understanding, which auto-selects an analyzer per file type and can return structured fields as YAML front matter — billed per Azure API call.
Advantages for LLM Text Analysis
- ✓One dependency instead of separate PDF, DOCX, PPTX, and XLSX parsers, with format support installed à la carte via extras like `[pdf]` or `[docx]`
- ✓Markdown output keeps headings, lists, and tables recognizable, so a chunking step downstream doesn't have to guess document structure from raw text
- ✓MIT license, 168,940 GitHub stars, and active maintenance from Microsoft
- ✓Azure Content Understanding integration adds structured field extraction and video support without a separate SDK
Important Considerations and Security
- △Conversion quality depends on the source file — the README itself doesn't claim OCR or scanned-PDF handling matches a dedicated document AI service
- △Azure Content Understanding and Document Intelligence are paid add-ons: every `convert()` call routed through them is a billable Azure API request
- △It performs I/O with the privileges of the whole process — the README's own security notice warns against passing untrusted input without sanitizing paths, URI schemes, and network destinations first
- △Plugins are third-party and unvetted by the core maintainers; enabling them (`--use-plugins`) runs whatever code the plugin author shipped
- △It only converts text out — chunking, embedding, and cleanup for a RAG pipeline are still on you
MarkItDown vs. Other Text Extractors
Common Questions
MarkItDown converts PDF, PowerPoint, Word, and Excel files, images (via EXIF metadata and OCR), audio (via EXIF metadata and speech transcription), HTML, CSV/JSON/XML, ZIP archives, EPubs, and YouTube URLs into Markdown.
MarkItDown is not built for that. Its own README says the output is meant for text analysis tools, not high-fidelity human-facing conversion, so complex layouts get simplified rather than reproduced exactly.
MarkItDown can route conversion through Azure Content Understanding by passing a cu_endpoint; it auto-selects an analyzer per file type, supports audio and video that built-in converters can't handle, and can return extracted fields as YAML front matter — each call is a billable Azure API request.
MarkItDown performs I/O with the same privileges as the process running it, similar to open() or requests.get(). The README recommends sanitizing untrusted input and calling the narrowest conversion function, like convert_local() or convert_stream(), instead of the permissive convert().
MarkItDown supports third-party plugins, off by default and enabled with --use-plugins. The official markitdown-ocr plugin, for example, adds LLM-Vision OCR to PDF, DOCX, PPTX, and XLSX conversion without extra ML dependencies.
MarkItDown requires Python 3.10 or higher, per the project's prerequisites, and the README recommends installing it inside a virtual environment to avoid dependency conflicts.
The problem it solves
Documents that need to reach an LLM usually arrive as PDF, DOCX, PPTX, XLSX, or a scanned image — formats a language model can't read directly, and formats where naive text extraction throws away the headings, tables, and list structure a model could otherwise use. MarkItDown exists to close that specific gap: turn a mixed pile of Office and PDF files into Markdown a model can parse the way it was trained to.
Best use cases
- •Feeding a batch of PDFs and Office documents into a RAG index — convert once, then chunk and embed the Markdown
- •Extracting invoice or contract fields at scale by routing PDFs through the Azure Content Understanding backend, which returns extracted values as YAML front matter instead of requiring a separate parsing step
- •Piping a YouTube URL or an audio file into a text pipeline via its built-in transcription support
- •Unzipping and converting an archive of mixed file types in one pass, since MarkItDown iterates over ZIP contents automatically
Who should try it — and who should skip
Try MarkItDown if you're building a RAG pipeline or LLM app and need PDFs, Office files, or images turned into parseable Markdown without hand-rolling a parser per format. Skip it if your output needs to look right to a human reader, or if you need OCR/document-AI accuracy beyond what the built-in converters or Azure add-ons give you — weigh that before committing budget to the Azure Content Understanding path, since it's billed per call.
Related repositories
Still deciding about MarkItDown?
One click hands the question to an AI along with this page — see what it says about MarkItDown.