Third-party toolUpdated 2026.11.16

MarkItDown Setup Guide: Installation, Examples and Fixes

MarkItDown installation and getting started: client setup or a local workflow, three practical examples, tested findings, common errors, costs and alternatives.

Aaron recommends Open official GitHub

Microsoft MarkItDown converts common file formats into Markdown for reading and downstream AI work. It is a practical first step for turning a report into text without building a document pipeline. Check the output before summarizing: successful conversion can still produce empty text or misleading table structure.

Install and choose a working environment

Tool version 0.1.9. Documentation checked 2026-11-16. The upstream source snapshot and installed package are pinned separately; the snapshot is not claimed to be the package’s release commit.

Create a project virtual environment first (python -m venv .venv), activate it using your shell’s normal procedure, and run the install command in that environment. The recorded Python tests used Linux/Python 3.12; other operating systems were not locally validated.

python -m pip install "markitdown[pdf,docx]==0.1.9"
markitdown --help
markitdown report.pdf -o report.md

This package is a CLI/Python library, not an MCP server configured by the install command above. Run the examples in the project’s environment and give the resulting files to your assistant.

  • Claude Code: open the project, ask it to inspect the saved script/output, and confirm the interpreter path before execution.
  • Codex: open the same workspace, provide the script/output filename, and ask for a review or a locally permitted run.
  • Cursor: choose the project’s Python interpreter, run the command in its terminal, then attach the resulting file in chat.

These are file/terminal workflows, not a claim of a vendor-specific integration. The three client interfaces were not tested locally.

Three practical uses

1. Convert a text PDF

markitdown report.pdf -o report.md

Expected: Open report.md and compare headings, key values and paragraphs with the PDF.

2. Convert meeting notes

markitdown meeting.docx -o meeting.md

Expected: Inspect meeting.md, especially column labels and any embedded tables.

3. Prepare a grounded summary

Read meeting.md. List decisions, owners and deadlines with supporting quotes. Mark absent fields as not provided, and flag possible conversion errors first.

Expected: a response that follows the stated scope and exposes the requested source or tool result. Verify those references before acting.

What our tests established

In the 0.1.9 isolated run, a text PDF retained its sentence while a PDF without a text layer returned success with effectively empty output. The HTML table retained headers; the DOCX fixture placed labels in a data row. OCR, Azure and other formats were not tested.

Tests were run by Codex on synthetic data; no claim of the owner personally testing or reviewing this guide. Examples added above are documentation-based unless included in that recorded scope.

Common errors and fixes

Conversion succeeds with empty text

Check whether the PDF has selectable text. Use a separate OCR workflow when needed and reject empty output.

DOCX headers appear as data

Compare the Word table settings and output. Use a structured parser when downstream code depends on headers.

Missing converter dependency

Install the documented extras for your format and run the CLI from that same Python environment.

Limits, costs and license

MIT licensed. This local conversion path needs no model API. Optional cloud or model features have separate credentials, data handling and fees. Markdown is not a reconstruction of the original layout.

When to choose an alternative

  • When you need document structure and table metadata:Docling。

  • For a PDF-specific Python API:PyMuPDF4LLM。

FAQ

Is MarkItDown from Microsoft?

Yes; this guide covers the official microsoft/markitdown project.

Is MarkItDown itself an MCP server?

This page uses the core CLI. An MCP wrapper is a separate installation and integration path.

Can I convert files without uploading them?

Yes, the basic conversion shown is local. Optional API-backed features have different data handling.

Official sources

If table structure matters to downstream code, compare Docling's table preservation. For PDF input, also see PyMuPDF4LLM's parsing workflow.

Subscribe to AI tool picks and practical advice

Get worthwhile tool picks, test findings and important updates in your inbox.

Get a monthly-updated list of AI tools and Skills right away. We email when there are worthwhile tool picks, test findings or important updates. Unsubscribe anytime. Privacy

Almost done: check your inboxClick the button in the confirmation email and you will get the download link for the tool list. If you do not see it, check your spam or Promotions folder.

Or follow us on: