markitdown-rs

markitdown-rs

markitdown-rs converts PDF, Word, PowerPoint, Excel, HTML, EPUB, Outlook and web pages to Markdown for LLMs and RAG pipelines. It is Microsoft's markitdown CLI rewritten in Rust as one 4.5 MB binary: the same command and the same Markdown, byte for byte, without a Python environment. From the command line it is usually hundreds of times faster (median 408× over 231 real-world files, about 15× on the largest PDFs and spreadsheets); in process, 4–50× faster.

brew install majiayu000/tap/markitdown-rs   # or: cargo install markitdown-rs

markitdown report.pdf > report.md

Prebuilt binaries for macOS (Apple silicon and Intel) and Linux x86_64 are on the releases page. It also runs as an MCP server for AI agents (markitdown mcp, stdio or HTTP) and has a Python module with markitdown's API, plugins included.

Example

A PDF form becomes a Markdown table, exactly as markitdown renders it (tests/fixtures/pdf/gen-form-mixed.pdf):

$ markitdown order.pdf

Purchase order summary

... Thank you for your order.

URLs work too, with markitdown's Wikipedia and YouTube handling:

$ markitdown https://en.wikipedia.org/wiki/Markdown | head -3

Markdown

Plain text markup language

markitdown-rs vs. the alternatives

Full feature-by-feature table, with how each number was measured: markitdown vs markitdown-rs.

Why

markitdown is the de facto "documents to Markdown for LLMs" tool, but using it from a shell, CI job or non-Python service means shipping a Python environment with mammoth, pdfminer.six, pdfplumber, pandas, openpyxl, BeautifulSoup, python-pptx, magika and onnxruntime. Its most requested features include brew and binary installs (#1179, #25) and lighter dependencies (#1234).

markitdown-rs targets output compatibility. It does not try to produce "better" Markdown: it reproduces markitdown's output, quirks included (pipes in table cells, Heading 7–9 as plain text, pdfminer's (cid:N) placeholders, pandas' NaN cells), so you can swap the binary without changing anything downstream.

Compatibility

Every fixture is converted by both implementations and compared byte for byte in cargo test against Python markitdown 0.1.9 (see Parity testing): 408 files, the 6,705 inputs of the html5lib tokenizer suite through the HTML converter, and 13 pages converted as if fetched from Wikipedia, Bing and YouTube URLs.

Sources are files and stdin as in markitdown, plus http:// / https:// URLs (with markitdown's Accept header and stream detection from the response), file: and data: URIs.

What each converter covers:

• DOCX follows mammoth 1.13: headings, bold/italic/underline/strike, lists, tables with merged and nested cells, hyperlinks (including linked pictures), footnotes and endnotes, images, equations (OMML to LaTeX), text boxes, checkboxes and tracked changes.
• PPTX follows python-pptx: titles, text in reading order, groups, tables, pictures, charts (bar, line, pie, area, radar, scatter, bubble) and notes.
• PDF is a port of pdfminer.six and the parts of pdfplumber markitdown uses: xref tables and streams (with the fallback for broken files), object streams, Flate/LZW/ASCII85/ASCIIHex/RunLength with predictors, RC4 and AES encryption (empty user password), Type1/TrueType/Type3/CID fonts with ToUnicode maps, the standard 14 fonts' metrics, embedded TrueType cmaps and the predefined CJK CMaps, form XObjects, pdfminer's layout analysis, and markitdown's borderless-table detection on pdfplumber word positions.
• XLSX/XLS follow pandas' read_excel (openpyxl/xlrd value conversion, dtype inference, to_html), one table per sheet.
• HTML ports CPython's html.parser, BeautifulSoup's tree builder and markdownify with markitdown's overrides; Wikipedia, Bing and YouTube pages get their dedicated converters when the source URL says so.
• MSG reads the MAPI properties from the OLE container (code pages included); EPUB walks the OPF spine; ZIP converts every member.
• Images and audio print exiftool metadata when exiftool is installed, as markitdown does.
• YouTube pages get the video's transcript (### Transcript), fetched the way markitdown's optional youtube-transcript-api does.

Known differences:

• PDF text-box order on rare layouts. pdfminer breaks ties between equal box distances by id(), a CPython memory address. markitdown-rs uses creation order instead. Of 313 PDFs tried (all of DP-Bench, arXiv papers, a 10-K, CJK manuals, other projects' test files) 308 are identical, one polyglot file is rejected by both, and 4 differ only in where a tied box lands (they match a pdfminer patched to use creation order).
• Content sniffing uses rules instead of magika's model, so files without an extension (or with a wrong one) can be routed differently; charset detection uses chardetng instead of charset_normalizer, which disagrees on short legacy 8-bit text and on Outlook messages that declare the wrong code page (tests/known-diffs.txt).
• Style maps embedded by mammoth (a mammoth/style-map part) are ignored by the Rust converter; the Python module applies them when given a style_map (see Python).
• Deeply nested input. HTML nested deeper than Python's recursion limit allows (493 elements) falls back to plain text exactly where markitdown does, with the same warning, however deep it goes. Word tables nested 5000 deep make Python fail; markitdown-rs stops at 512 levels of XML nesting with an error.
• UTF-16 HTML with a byte order mark is decoded by its BOM. markitdown decodes UTF-16LE but turns UTF-16BE pages into mojibake.
• Wikipedia answers Python's default python-requests User-Agent with HTTP 403; markitdown-rs sends its own and gets the page.

The command line does not do what markitdown leaves to optional Python packages or cloud services: audio transcription (markitdown's speech_recognition calls Google's unofficial speech API with a key built into that library, and needs ffmpeg), LLM image captions, Azure Document Intelligence / Content Understanding (-d, --use-cu) and plugins (-p). The Python module does all of these, and its own markitdown command has the original's full set of flags. Like markitdown, legacy .doc and .ppt files are not converted.

Install

With Homebrew (macOS, Linux x86_64):

brew install majiayu000/tap/markitdown-rs

From crates.io (Rust 1.88+):

cargo install markitdown-rs

Prebuilt binaries for macOS (arm64, x86_64) and Linux (x86_64) are attached to each release, with SHA-256 sums:

curl -L https://github.com/majiayu000/markitdown-rs/releases/download/v0.2.1/markitdown-v0.2.1-aarch64-apple-darwin.tar.gz | tar xz

./markitdown-v0.2.1-aarch64-apple-darwin/markitdown --version

From a checkout: cargo install --path crates/markitdown-rs. All of these install a binary named markitdown. The PyPI package is also available: python -m pip install "markitdown-rs[mcp]" in a fresh Python 3.10+ environment.

Usage

The flags mirror the Python CLI:

markitdown [filename] [-o OUTPUT] [-x EXTENSION] [-m MIME_TYPE] [-c CHARSET] [--keep-data-uris]

markitdown report.pdf                   # Markdown on stdout

markitdown book.xlsx -o book.md # write to a file (no trailing newline, like Python) markitdown https://example.com/a.docx # fetch a URL cat report.docx | markitdown -x docx # stdin, with an extension hint markitdown --keep-data-uris report.docx # keep images as full base64 data URIs

As in markitdown, the format comes from the hints (extension, MIME type, charset) and from the file contents, and converters are tried in markitdown's order until one succeeds.

Limits that markitdown does not have, so that hostile files fail cleanly instead of exhausting memory or hanging (environment variables, also Options fields in the library):

As a library (markitdown-core; URL loading is the optional fetch feature):

use markitdown_core::{StreamInfo, convert};

let data = std::fs::read("report.pdf")?; let md = convert(&data, &StreamInfo::from_path("report.pdf"), &Default::default())?;

MCP server

markitdown mcp serves the Model Context Protocol on stdio with the same tool as microsoft/markitdown-mcp: convert_to_markdown(uri) for http:, https:, file: and data: URIs (local paths work too). Logs go to stderr, so stdout carries only JSON-RPC.

Claude Code:

claude mcp add markitdown -- markitdown mcp

Claude Desktop (claude_desktop_config.json) and Cursor (~/.cursor/mcp.json, or .cursor/mcp.json in a project) use the same block:

{

"mcpServers": { "markitdown": { "command": "markitdown", "args": ["mcp"] } } }

Desktop apps may not see your shell's PATH; if the server does not start, use the full path from which markitdown (e.g. ~/.cargo/bin/markitdown) as command.

Tool name, input and output schemas,