microsoft/markitdown

MarkItDown – File‑to‑Markdown conversion for LLM pipelines

What it is – A lightweight Python library and CLI that turns a wide range of document types (PDF, Word, PowerPoint, Excel, images, audio, HTML, JSON, CSV, ZIP, YouTube videos, EPubs, …) into Markdown. The output keeps structural cues such as headings, lists, tables and links, making the result easy for large language models to ingest.

Why Markdown? – LLMs are trained heavily on Markdown; the format is plain‑text yet expressive and token‑efficient, so converting raw files to Markdown improves downstream text‑analysis quality.

Key capabilities

• Local, offline converters for common office formats.
• Optional cloud back‑ends:
  • Azure Document Intelligence – layout‑aware extraction.
  • Azure Content Understanding – multimodal (doc, image, audio, video) conversion with structured field extraction (YAML front‑matter) and custom analyzers.
• LLM‑powered image description – plug in any OpenAI‑compatible client (e.g., gpt‑4o) to generate captions for embedded images.
• OCR plugin (markitdown-ocr) that uses LLM vision models for image‑based text without extra binaries.
• Plugin system – third‑party extensions can add new formats; discoverable via the #markitdown‑plugin tag.
• Security‑aware API – narrow conversion functions (convert_local, convert_stream, convert_response) let callers limit I/O scope.

Installation

# Core + all optional format support
pip install 'markitdown[all]'
# Or pick only what you need, e.g. PDF + DOCX
pip install 'markitdown[pdf,docx]'

For development, clone the repo and install the package in editable mode:

git clone https://github.com/microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

Command‑line usage

# Simple conversion, stdout → markdown
markitdown path/to/file.pdf > out.md

# Specify output file
markitdown path/to/file.pdf -o out.md

# Pipe data
cat file.pdf | markitdown > out.md

Add --use-plugins to enable any installed plugins, or --list-plugins to see what’s available.

Python API (basic)

from markitdown import MarkItDown
md = MarkItDown(enable_plugins=False)   # set True to load plugins
result = md.convert('report.xlsx')
print(result.markdown)

Azure Document Intelligence example:

md = MarkItDown(docintel_endpoint='https://<resource>.cognitiveservices.azure.com/')
print(md.convert('file.pdf').markdown)

Azure Content Understanding with custom analyzer:

md = MarkItDown(
    cu_endpoint='https://<cu>.cognitiveservices.azure.com/',
    cu_analyzer_id='my-invoice-analyzer'
)
print(md.convert('invoice.pdf').markdown)   # includes YAML front‑matter

LLM‑driven image description:

from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model='gpt-4o')
print(md.convert('photo.jpg').markdown)

Extending the tool

• Install third‑party plugins (pip install markitdown-ocr, etc.).
• Create your own plugin by following the sample in packages/markitdown-sample-plugin and tag the repo with #markitdown-plugin.
• Control which optional dependencies are installed to keep the environment lightweight.

Security considerations MarkItDown runs with the same file‑system and network permissions as the calling process. Users must sanitize untrusted inputs, restrict paths/URLs, and prefer the narrowest conversion function (convert_local, convert_stream, …) to limit exposure.

Running tests

cd packages/markitdown
pip install hatch
hatch shell
hatch test

Or use the provided DevContainer.

License & contribution Open‑source under the MIT license (as per the PyPI page). Contributions are welcomed but must stay within the library scope—no web services, GUIs, or hosted APIs are accepted. A Contributor License Agreement is required for PRs.