One command turns common files into LLM-ready Markdown
MarkItDown v0.1.7 accepts PDFs, Word documents, spreadsheets, slide decks, images, audio, HTML, text formats, ZIP archives, EPUBs, and YouTube URLs. You can call it from Python, pipe a file into the CLI, or write the result with -o. That makes it useful as a first normalization step before search, extraction, or a language-model prompt.
The design target is machine consumption. Microsoft says the Markdown may look reasonable to a person, yet it is not the best choice for high-fidelity human documents. ZIP conversion walks through archive contents, and optional plugins add formats without putting every dependency in the core package. Plugins stay disabled unless the caller passes the relevant switch or enables them in Python.
Python 3.10 and format extras keep the base path narrower
The package requires Python 3.10 or newer. Its base dependency list covers HTML parsing, HTTP requests, character detection, XML safety, Markdown conversion, and file-type detection. Installing only pdf, docx, and pptx is a more sensible production choice than taking every extra when those are the only inputs.
Developers work from packages/markitdown/ rather than the repository root. The contribution guide uses Hatch for its environment and tests. Our measured checkout contained 173 files, about 16,012 source lines, and 25 MB. It had a tests directory and 2 CI workflow files, while our scan found no Dockerfile at commit 4459ed0.
What happened when we ran it
We measured a 39-second install of 76 packages, using 359 MB on disk, after cloning commit 4459ed0 into our unprivileged Debian sandbox. The build succeeded in 7 seconds, while pip-audit found 0 known vulnerabilities. The container had 3 CPUs, 8 GB of RAM, and no secrets. The full dependency set installed cleanly, although its disk footprint is substantial for a utility described as lightweight.
The test step failed after 203 seconds. Pytest reported 443 passed and 1 failed out of 444, with 4 skipped. test_speech_transcription expected the transcript to contain the numbers 1 through 5; the returned text was ### audio transcript: 1 2 3 4. The log shows that 5 was absent. It does not show why, so the defensible conclusion is that audio transcription did not pass the complete suite in our sandbox.
Local files need no key, while Azure conversion is billable
MarkItDown v0.1.7 CLI and Python conversions run locally without an API credential. Image descriptions require a supplied model client and model name. Azure Document Intelligence needs its service endpoint. Content Understanding can handle documents, images, audio, and video, route work to prebuilt or custom analyzers, and add extracted fields as YAML front matter. The README states that each routed conversion is a billable Azure API call.
That split gives teams a useful choice. Local parsers suit ordinary text extraction and private files. Azure may make sense for scanned PDFs, complex tables, video, or schema-specific fields, but it adds credentials, service cost, and data handling decisions. The cu_file_types setting can limit paid routing to selected formats rather than sending every supported input to the service.
The permissive URI API needs a security boundary
In v0.1.7, convert() can accept local files, remote URIs, and streams with the privileges of the running process. Microsoft tells server developers to validate file paths, URI schemes, network destinations, loopback addresses, link-local ranges, and metadata-service addresses. A service that accepts user input should prefer convert_local(), fetch a permitted URL itself before calling convert_response(), or pass an already opened stream to convert_stream().
The warning is unusually direct and should affect architecture. The main repository will not accept web servers, REST APIs, hosted conversion services, or graphical applications as in-scope contributions. If you build a public uploader around MarkItDown, authentication, size limits, path isolation, network egress rules, and sandboxing belong to your application. The library does not claim to supply that service layer.
PDF fidelity remains a poor fit for exact reading order
The README's fidelity disclaimer is backed by concrete reports. Open issue 2336 reproduces reversed Arabic text and broken table associations with MarkItDown v0.1.7. Issue 41 describes a PDF 10-K losing tables and titles. They do show why a valid Markdown file is not enough evidence for contracts, financial tables, RTL text, or multi-column papers.
Sample representative files before adoption, then compare headings, reading order, table cells, equations, and OCR text against the originals. The same rule applies to audio after our 203-second test run missed the final spoken number. MarkItDown is easier to trust when downstream work tolerates approximate extraction or checks important fields independently. Docling is the stronger trial when layout recovery is the central requirement.
The MCP server exposes 1 powerful local tool without authentication
The separate markitdown-mcp package offers convert_to_markdown(uri) over STDIO, Streamable HTTP, or SSE. That one tool accepts http, https, file, and data URIs. Its documentation says the server has no authentication, runs with the user's privileges, and is intended for trusted local agents. HTTP modes bind to localhost by default; the project recommends a container when connecting it to Claude Desktop and warns against binding other interfaces.
September activity is high, and the open queue is large
GitHub showed 178,371 stars and a last push on September 4, 2026. Release v0.1.7 shipped on July 29 with PowerPoint chart, SVG, and equation fixes. The repository had 315 open issues and 314 open pull requests when fetched. Recent issue closures on September 5 and 6 show maintainer activity, while 629 combined open items mean users should search existing reports before diagnosing a converter edge case.
MarkItDown earns a place in a trusted ingestion script because the API is small, format extras are selectable, and the local path is easy to inspect. The 359 MB full install, one failed speech test, PDF fidelity reports, and broad I/O permissions set its limits. Pandoc is better for publishing-format conversion, while Unstructured fits pipelines that need document elements and chunking instead of one Markdown string.