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)#

bash

pipx install 'markitdown[all]'

Install via pip#

bash

pip install 'markitdown[all]'

Minimal install (specific formats only)#

bash

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

Supported Formats#

FormatExtensionNotesPDF.pdfPreserves structure, tables, linksWord.docxHeadings, lists, tablesPowerPoint.pptxSlides to MarkdownExcel.xlsx, .xlsTable dataImages.png, .jpg, etc.EXIF metadata + OCRAudio.wav, .mp3Speech transcriptionHTML.html, .htmWeb contentYouTubeURLVideo transcriptionZIP.zipIterates over contentsEPub.epubE-booksText.csv, .json, .xmlText-based formats

CLI Usage#

Basic Conversion#

bash

# 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#

bash

cat document.pdf | markitdown

Image OCR#

bash

markitdown screenshot.png -o text.md

YouTube Video#

bash

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

Python API Usage#

python

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#

OptionDescriptionExample-o, --outputOutput file-o output.md``--formatOutput format (default: markdown)--format json``--pagesSpecific pages--pages "1,3,5-7"``--image-outputImage handling--image-output external``--quietSuppress output--quiet

MCP Server#

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

bash

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+:

bash

# macOS
brew install openjdk@17

# Ubuntu
sudo apt install openjdk-17-jdk

Permission denied#

Use pipx or virtual environment:

bash

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