MarkItDown

Microsoft's lightweight Python utility for converting various files to Markdown for use with LLMs and related text analysis pipelines.

Installation

Prerequisites

• Python 3.10+
• Java 11+ (for some converters)

Install via pipx (recommended)

pipx install 'markitdown[all]'

Install via pip

pip install 'markitdown[all]'

Minimal install (specific formats only)

pip install 'markitdown[pdf,docx,pptx]'

Supported Formats

CLI Usage

Basic Conversion

# PDF to Markdown
markitdown document.pdf > output.md

# Word to Markdown
markitdown document.docx -o output.md

# PowerPoint to Markdown
markitdown presentation.pptx -o output.md

Pipe Input

cat document.pdf | markitdown

Image OCR

markitdown screenshot.png -o text.md

YouTube Video

markitdown "https://youtube.com/watch?v=..." -o transcript.md

Python API Usage

from markitdown import MarkItDown

# Initialize
md = MarkItDown()

# Convert file
result = md.convert("document.pdf")
print(result.text_content)

# Convert from stream
with open("document.pdf", "rb") as f:
    result = md.convert_stream(f)
    print(result.text_content)

Options

MCP Server

MarkItDown provides an MCP (Model Context Protocol) server for integration with LLM applications:

pip install markitdown-mcp

Best Practices

1. Batch processing: Process multiple files in one call for efficiency
2. Format selection: Use minimal install if only specific formats needed
3. OCR quality: Ensure 300 DPI+ for scanned documents
4. Output review: Always verify Markdown output for complex documents

Troubleshooting

Java not found

Install Java 11+:

# macOS
brew install openjdk@17

# Ubuntu
sudo apt install openjdk-17-jdk

Permission denied

Use pipx or virtual environment:

python3 -m venv ~/.venvs/markitdown
source ~/.venvs/markitdown/bin/activate
pip install 'markitdown[all]'

References

• GitHub: https://github.com/microsoft/markitdown
• PyPI: https://pypi.org/project/markitdown/
• MCP Server: https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp