microsoft/markitdown
Developer ToolsPython library and CLI that converts PDFs, Office files, HTML, audio and other inputs into Markdown for LLM pipelines.
What it does
MarkItDown is a Python utility that turns documents into Markdown for LLM prompts and text-analysis pipelines. It targets formats such as PDF, PowerPoint, Word, Excel, HTML, CSV/JSON/XML, EPUB, images, audio, ZIP archives, and YouTube URLs, and aims to preserve structural elements like headings, lists, tables, and links rather than produce a high-fidelity human-facing document. The output is often readable, but the intended consumer is a text-analysis tool. The project is maintained by Microsoft and is installable from PyPI.
Image captioning and speech transcription call web-hosted services. For PDFs, a commenter observed that the implementation wraps PDFMiner; they suggested using PDFMiner directly if PDF extraction is the only requirement (discussion, PDFMiner docs).
Quick start
MarkItDown requires Python 3.10–3.14. Create a virtual environment first to avoid dependency conflicts (prerequisites).
python -m venv .venv
source .venv/bin/activate
pip install 'markitdown[all]'
The [all] extra installs every optional format dependency. To keep the install smaller, install only the formats you need, for example pip install 'markitdown[pdf,docx,pptx]' (optional dependencies).
Convert a file from the shell:
markitdown path-to-file.pdf > document.md
# or write directly to a file
markitdown path-to-file.pdf -o document.md
# or pipe input
cat path-to-file.pdf | markitdown
In Python, call the library directly:
from markitdown import MarkItDown
md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.markdown)
For a zero-install run on a machine with uv, a 2024 discussion suggested uvx markitdown path-to-file.pdf, which caches packages after the first invocation (HN comment). This is a community suggestion, not the documented installation method.
Cloud and plugin options
For higher-quality extraction of scanned PDFs and complex tables, or for audio/video input, Azure Content Understanding can be used with --use-cu --cu-endpoint "<content_understanding_endpoint>". Azure Document Intelligence is also supported via -d and -e "<document_intelligence_endpoint>", or through the docintel_endpoint argument in Python. Both are billable Azure services, and some optional analysis features incur additional charges (Document Intelligence pricing).
Third-party plugins are disabled by default; list and enable them with markitdown --list-plugins and markitdown --use-plugins. The separate markitdown-ocr plugin adds OCR for embedded images in PDF, DOCX, PPTX and XLSX using an LLM vision client (OCR plugin).
Usage constraints
MarkItDown performs I/O with the privileges of the current process, so untrusted input must be validated before conversion. In hosted or server-side applications, restrict file paths, URI schemes, and network destinations, and block private, loopback, link-local and metadata addresses. Prefer the narrowest API for the job — convert_local() for local files, convert_response() for fetched responses, convert_stream() for byte streams — rather than the permissive convert() (security considerations).
Image captioning, speech transcription, and both Azure integrations depend on external web services; local-only use requires installing only the optional dependencies you need. The repository is a library and CLI, not an end-user app: web servers, REST APIs, and desktop or mobile UIs are explicitly out of scope, and new formats are generally expected as third-party plugins (contribution scope).
HotRepo's take
MarkItDown entered the all-language daily snapshot on 2026-09-07 with about 180k stars and roughly 0.8k stars gained that day; gains then rose to about 2.0k on September 8 and 9, before a Python-language daily record on 2026-11-19 showed about 526 gained and a best position of 10 on that list. The numbers span snapshots with different scopes, so they should not be read as a single continuous trend. The 2024 Hacker News thread drew 81 comments; an early commenter who had built an in-house converter called the implementation reasonable but suggested passing images directly to multimodal models and avoiding Markdown tables for spreadsheets (HN comment). Another commenter argued the hard part is the long tail of messy documents, where clean DOCX conversion is simple but screenshots and complex tables are not (HN comment). That framing matches the project's design: a small common pipeline for many formats, with cloud services and plugins available when extraction quality matters more.
Written by AI from the project's README, updated . The project's own docs are the source of truth.
Hacker News
You might also like
- Jamailar/Weave-OfficeA Rust desktop office suite that opens documents, sheets, slides, PDFs, Markdown and code in one tabbed app, with a CLI for AI agents.
- gotenberg/gotenbergA Docker-based HTTP API that converts HTML, URLs and office documents to PDF and post-processes them.
- langfuse/langfuseTrace, evaluate and iterate on LLM and agent applications from one open platform, whether cloud-managed or self-hosted.