Convert various document formats (PDF, Word, PowerPoint, Excel, images, audio, HTML, etc.) to Markdown using Microsoft's markitdown tool. Supports OCR, audio transcription, and YouTube video extraction.
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
| Format | Extension | Notes |
|---|---|---|
| Preserves structure, tables, links | ||
| Word | .docx | Headings, lists, tables |
| PowerPoint | .pptx | Slides to Markdown |
| Excel | .xlsx, .xls | Table data |
| Images | .png, .jpg, etc. | EXIF metadata + OCR |
| Audio | .wav, .mp3 | Speech transcription |
| HTML | .html, .htm | Web content |
| YouTube | URL | Video transcription |
| ZIP | .zip | Iterates over contents |
| EPub | .epub | E-books |
| Text | .csv, .json, .xml | Text-based 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
| Option | Description | Example |
|---|---|---|
-o, --output | Output file | -o output.md |
--format | Output format (default: markdown) | --format json |
--pages | Specific pages | --pages "1,3,5-7" |
--image-output | Image handling | --image-output external |
--quiet | Suppress output | --quiet |
MCP Server
MarkItDown provides an MCP (Model Context Protocol) server for integration with LLM applications:
pip install markitdown-mcp
Best Practices
- Batch processing: Process multiple files in one call for efficiency
- Format selection: Use minimal install if only specific formats needed
- OCR quality: Ensure 300 DPI+ for scanned documents
- 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
Related skills
- Downloads
- 1.2kAll time
- Security audit
- Pass
- Last updated
- 6mo ago
- Current version
- v1.0.0
- License
- MIT-0
