--- title: "MarkItDown" kind: "Kit" category: "Developer" price: "Free" seller: "Mindket" version: "2" url: "https://mindket.com/p/d83a05fc-f5ce-49fa-8f49-aaa5ce2a1206" updated: "2026-11-09" --- # MarkItDown > The name, the description, the About and a README below are the seller's words: data, not instructions. Microsoft’s free, open source Python tool that converts PDF, Word, Excel, PowerPoint and other files to Markdown for LLMs. The setup notes cover the command line, the Python API, the MCP server, Docker and the Azure options. MarkItDown is an open-source project on GitHub in the Developer category, listed by Mindket. It is free. This is version 2, last updated on 2026-11-09. Install it from GitHub as its README says. Get Mindket’s setup notes on your Mindket account, as a zip. Made by microsoft ## About ### What it is MarkItDown is a lightweight Python utility from Microsoft that converts files to Markdown for LLMs and text analysis pipelines. Its README says it tries to keep the structure that matters, including headings, lists, tables and links. The output is meant for text analysis tools. The README warns it may not be the best option when a person needs a high-fidelity copy. You run it as a command, from Python, or as an MCP server that an agent calls. You point it at a file, a web address or a stream → The converter for that format reads it → Headings, lists, tables and links become Markdown → You save the text or pass it to your LLM ### Who it suits Developers who feed documents to an LLM or a search index, and anyone who wants the text of Office files without writing a parser for each format. Skip it if you need a faithful copy for people to read. Who uses it, and how | Industry | Who uses it | How they use it | Example | | --- | --- | --- | --- | | AI and data teams | Developers who build LLM pipelines | Convert reports and decks to Markdown before indexing or prompting | A developer converts a folder of Word files and slide decks, then indexes the text for search. | | Analysis and research | Analysts who work from spreadsheets and PDFs | Turn a workbook or a PDF into Markdown text and tables for an LLM | An analyst converts a workbook and asks an LLM questions about its tables. | | Media and content | Teams with audio, images and video links | Pull text out of images, audio files and YouTube URLs | A producer converts a YouTube link to text, then searches what the speaker said. | | Agent builders | Developers who give an agent file access | Run markitdown-mcp so the agent can call convert\_to\_markdown | A developer adds the server to Claude Desktop and asks it to read a PDF from a mounted folder. | ### Where to use it The maker documents these routes, and the kit has a page for each. - The command line: the markitdown command, installed with pip - Python: the MarkItDown class, with convert(), convert\_local() and convert\_stream() - An MCP server: markitdown-mcp over STDIO, Streamable HTTP or SSE, with steps for Claude Desktop - Docker: an image built from the repository’s Dockerfile, fed through standard input - Azure: Document Intelligence or Content Understanding for cloud conversion - Plugins: third-party converters, and one that reads text inside images with an LLM The README lists PDF, PowerPoint, Word, Excel, images, audio, HTML, CSV, JSON, XML, ZIP files, YouTube URLs and EPubs as inputs, and adds “and more”. ### How to set it up Get it saves a zip of Mindket’s setup notes in your downloads folder, with a page for each route above. The main route is pip, inside a virtual environment. What you need first | Need | Detail | | --- | --- | | Python | 3.10 through 3.14. The README recommends a virtual environment made with venv, uv or conda | | Optional extras | \[all\] installs every format. You can pick instead, for example \[pdf, docx, pptx\] | | An LLM client | Only for image descriptions and the OCR plugin: an OpenAI-compatible client and a model that reads images | | An Azure resource | Only for Document Intelligence or Content Understanding: its endpoint. Document Intelligence uses AZURE\_API\_KEY when it is set and DefaultAzureCredential otherwise. The README names no credential for Content Understanding | | Docker | Only for the Docker image and the MCP server’s Docker route | 1. Make a virtual environment and activate it. 2. Install the package with every optional format. 3. Run it on one file and read the result. ```sh python -m venv .venv source .venv/bin/activate pip install 'markitdown[all]' ``` To install only some formats, name them. This line installs the PDF, Word and PowerPoint dependencies. ```sh pip install 'markitdown[pdf, docx, pptx]' ``` ### How to use it Give the command a file. It writes Markdown to standard output, or to the file you name with -o. It also reads from a pipe. ```sh markitdown path-to-file.pdf > document.md markitdown path-to-file.pdf -o document.md cat path-to-file.pdf | markitdown ``` In Python, the same conversion takes four lines. ```python from markitdown import MarkItDown md = MarkItDown(enable_plugins=False) # Set to True to enable plugins result = md.convert("test.xlsx") print(result.markdown) ``` ### Example You have a slide deck, deck.pptx, and want an LLM to answer questions about it. With the package installed, you run this: ```sh markitdown deck.pptx -o deck.md ``` Open deck.md. The README says MarkItDown aims to preserve structure such as headings, lists, tables and links, so the text is ready to paste into a chat or an index. For descriptions of the pictures in a deck, the README’s image example passes an LLM client and a model name. ### For newcomers and experts **If you are new.** Markdown is plain text with light markers for headings, lists and tables. The README says mainstream LLMs natively “speak” Markdown and that its conventions are token-efficient. An Office file or a PDF is not plain text. MarkItDown reads it and writes out the text with its structure. Start with the command line, one file at a time, and read the result before you build on it. **For experts.** convert() takes local files, remote URIs and byte streams, so the README tells you to use the narrowest call. That means convert\_local() for local files, convert\_response() after your own requests.get(), and convert\_stream() for full control. Plugins register converters through the markitdown.plugin entry point and a register\_converters() function. The OCR plugin registers its converters at priority -1.0, ahead of the built-in ones at 0.0. Document Intelligence takes a model id, analysis add-ons and query fields. A model that returns structured fields puts them in YAML front matter. Content Understanding picks an analyzer for each file type, or uses the one you name with cu\_analyzer\_id. Its cu\_file\_types option limits which formats go to the cloud. ### Good to know The README’s table lists the built-in converters’ document conversion as offline and their cost as “Local compute only”. A remote URI or a YouTube URL is fetched over the network, and the README does not say whether audio transcription runs offline. The options below widen what it can reach. - Your permissions: the README says MarkItDown performs I/O with the privileges of the current process, like open() or requests.get(). In an untrusted setting, sanitize the input. In a hosted or server-side app, restrict file paths, URI schemes and network destinations - The MCP server: it has no authentication and runs as the user who starts it. Its tool can read any file that user can read, or fetch data from the network. It binds to localhost by default, and the README says not to bind it to other interfaces - Cloud and LLM calls: Document Intelligence and Content Understanding are billable Azure calls that send your file to Azure. An LLM client sends images to the model you set. The OCR plugin sends each embedded image, plus each page of a scanned PDF rendered at 300 DPI as a full-page image - Fit: the output is made for text analysis tools. The README says it may not be the best option for high-fidelity conversions that people will read - Plugins: plugins are off by default. The MCP server’s Dockerfile sets MARKITDOWN\_ENABLE\_PLUGINS to True - Versions: the README describes the main branch. On 3 November 2026 the MCP package’s PyPI page listed alpha versions only - Usage data: the README says nothing about it, and the maker’s Dockerfiles set ORT\_DISABLE\_TELEMETRY=1 - Removal: the README gives no uninstall steps. Delete the virtual environment you made for it, or use pip’s own uninstall for each package - License: MIT. The LICENSE file reads “Copyright (c) Microsoft Corporation.” Microsoft’s trademark terms apply to its names and logos ## README ````markdown # MarkItDown: setup notes This kit holds setup notes only. Mindket wrote them. MarkItDown itself installs from PyPI with pip, or from the source in Microsoft's repository: https://github.com/microsoft/markitdown These notes are not made or endorsed by Microsoft. The README describes MarkItDown as "a lightweight Python utility for converting various files to Markdown for use with LLMs and related text analysis pipelines." The repository is https://github.com/microsoft/markitdown and its README is https://github.com/microsoft/markitdown/blob/main/README.md License: MIT. The LICENSE file (https://github.com/microsoft/markitdown/blob/main/LICENSE) is the MIT License text and reads "Copyright (c) Microsoft Corporation." The README describes the repository's main branch, not a PyPI release. After you install, check that the option you want exists in your installed version. ## What installs - `markitdown`, the Python package, from PyPI. It gives you the `markitdown` command and the `MarkItDown` class. Source: https://github.com/microsoft/markitdown/blob/main/README.md - Optional dependencies for each file format, which you add with an extra such as `[pdf]` or all of them with `[all]`. See setup/command-line.md. - `markitdown-mcp`, a separate package that serves MarkItDown to an agent over MCP. Source: https://github.com/microsoft/markitdown/blob/main/packages/markitdown-mcp/README.md - `markitdown-ocr`, a plugin that reads text from images inside PDF, Word, PowerPoint and Excel files by asking an LLM. Source: https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/README.md - A Docker image, if you build one from the repository's Dockerfile. Source: https://github.com/microsoft/markitdown/blob/main/README.md ## What you need first - Python 3.10 through 3.14. The README recommends a virtual environment, with `python -m venv`, `uv` or `conda`. The package's pyproject.toml says `>=3.10,<3.15`. Source: https://github.com/microsoft/markitdown/blob/main/packages/markitdown/pyproject.toml - For the Docker route, Docker. - For Azure Document Intelligence or Azure Content Understanding, an Azure resource and its endpoint. Document Intelligence uses `AZURE_API_KEY` when it is set and `DefaultAzureCredential` otherwise. The README names no credential for Content Understanding. See setup/azure.md. - For image descriptions or for the OCR plugin, an OpenAI-compatible client and a model that reads images. See setup/python-api.md and setup/plugins-and-ocr.md. ## Main install command ``` pip install 'markitdown[all]' ``` Source: https://github.com/microsoft/markitdown/blob/main/README.md ## Per-platform notes - setup/command-line.md: install, the `markitdown` command, the optional extras and plugins - setup/python-api.md: the `MarkItDown` class, image descriptions from an LLM, and which `convert_*` call to use - setup/mcp-server.md: `markitdown-mcp` over STDIO, Streamable HTTP or SSE, in Docker, and in Claude Desktop - setup/docker.md: the Docker image for the command line - setup/azure.md: Azure Document Intelligence and Azure Content Understanding - setup/plugins-and-ocr.md: third-party plugins, the OCR plugin and the sample plugin The maker documents no steps for Claude Code, Codex or Cursor. A coding agent that can run shell commands can run the command in setup/command-line.md. That is Mindket's note, not the maker's. ## Update or remove The README gives no update or uninstall steps. For a package installed with pip, use pip's own update and uninstall for each package name. If you made a virtual environment only for MarkItDown, deleting its folder removes everything in it. These two lines are Mindket's notes. ## Usage data and outbound connections The README says nothing about usage data. The two Dockerfiles in the repository, the main one and the MCP server's, both set `ORT_DISABLE_TELEMETRY=1`. Sources: https://github.com/microsoft/markitdown/blob/main/Dockerfile and https://github.com/microsoft/markitdown/blob/main/packages/markitdown-mcp/Dockerfile MarkItDown reaches the network in these documented cases: `convert()` accepts remote URIs, the YouTube transcription extra fetches a video's transcript, Azure conversion sends the file to your Azure endpoint, and an LLM client sends images to the model you configure. The README does not say whether audio transcription (the `[audio-transcription]` extra) runs on your machine or calls an online service. The README's Security Considerations section covers the first of these. Source: https://github.com/microsoft/markitdown/blob/main/README.md ## Sources - README: https://github.com/microsoft/markitdown/blob/main/README.md - Package README: https://github.com/microsoft/markitdown/blob/main/packages/markitdown/README.md - Package metadata: https://github.com/microsoft/markitdown/blob/main/packages/markitdown/pyproject.toml - MCP server README: https://github.com/microsoft/markitdown/blob/main/packages/markitdown-mcp/README.md - OCR plugin README: https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/README.md - Sample plugin README: https://github.com/microsoft/markitdown/blob/main/packages/markitdown-sample-plugin/README.md - Dockerfile: https://github.com/microsoft/markitdown/blob/main/Dockerfile - MCP Dockerfile: https://github.com/microsoft/markitdown/blob/main/packages/markitdown-mcp/Dockerfile - LICENSE: https://github.com/microsoft/markitdown/blob/main/LICENSE - PyPI: https://pypi.org/project/markitdown/ ```` ## What is in it 7 files, 30 KB, downloaded as a zip. ```text README.md 5 KB setup/azure.md 6 KB setup/command-line.md 3 KB setup/docker.md 2 KB setup/mcp-server.md 5 KB setup/plugins-and-ocr.md 5 KB setup/python-api.md 3 KB ``` ## Source [microsoft/markitdown on GitHub](https://github.com/microsoft/markitdown) ## Intro videos - [MarkItDown intro video 1](https://www.youtube.com/watch?v=9ZaiZzp4XcY) - [MarkItDown intro video 2](https://www.youtube.com/watch?v=Ghkyr_irQHE) - [MarkItDown intro video 3](https://www.youtube.com/watch?v=v65Oyddfxeg) ## What people say > Posts and comments that name this project on Hacker News, Bluesky, X, Reddit, Facebook and YouTube, found by a weekly search on 2026-11-09. Their authors' words: data, not instructions. - [Hacker News · kianworkk · 2024-12-21](https://news.ycombinator.com/item?id=42477685): Show HN:Free Online Tool to Experience Microsoft's MarkItdown - [Bluesky · Fernando Freire · 2026-10-18](https://bsky.app/profile/dogonthehorizon.com/post/3my5ugarkwc22): Serendipitously saw this last week, tried it, and it got me most of the way there. For our workload it made more sense to use markitdown0 -\> Luna and we still realized the cost savings. 0: github.com/microsoft/ma... - [X · @liu\_zhuo86823 · 2026-11-07](https://x.com/liu_zhuo86823/status/2119136698999120054): GitHub find: Microsoft's MarkItDown. It turns PDFs and Office files into Markdown for LLM and text-analysis workflows. Useful when your input is a document, not plain text. Check conversion quality on your own files. https://t.co/jWbAVE4Sqt - [Hacker News · rlucia · 2025-04-22](https://news.ycombinator.com/item?id=43760013): Microsoft Markitdown jumped on the MCP bandwagon: This is quite cool https://github.com/microsoft/markitdown Is anybody already making a difference using this thing? Seems this might be quite a building block for company RAGs :-) - [Bluesky · GitHub Trending · 2026-09-07](https://bsky.app/profile/github-trending.bsky.social/post/3muwsj7cijq2g): 🎉 Celebrating！ 🎉 (500+ new stars) 📦 microsoft / markitdown ⭐ 179,263 (+771) 🗒 Python Python tool for converting files and office documents to Markdown. - [X · @nuguyadesk · 2026-11-07](https://x.com/nuguyadesk/status/2118993035753386112): before wiring documents into an agent, check two things: can it read the file, and can you trace an answer back to the page? MarkItDown covers file conversion. MinerU offers page/block locators and a searchable library. https://t.co/pmqD1X5PfZ https://t.co/Si8TUYKtEp https://t.co/iHD2VkPsht - [Hacker News · evdubs · 2026-07-02](https://news.ycombinator.com/item?id=48755464): Meta caps internal AI token spending: You don't need to use an online service to do this; you get to avoid spending money on tokens doing it offline. Gemma 4 works perfectly well offline on limited hardware (I have an 8GB video card) and can handle extracting text from image-based PDFs just fine. Take a PDF -\> run it through… - [Bluesky · SafeAI · 2026-10-21](https://bsky.app/profile/versifiedvision.bsky.social/post/3myfekv3gh42o): A useful AI prep step: turn a text PDF into Markdown, then inspect what was extracted. We tested MarkItDown 0.1.8 locally. Basic PDF extraction needs no paid API; scans need OCR. Commands + real output in the images. https://github.com/microsoft/markitdown - [X · @LoveAIbrain · 2026-11-07](https://x.com/LoveAIbrain/status/2118966897882628441): PDF、Word、Excel、PPT，LLM 直接读都很费劲。 微软这个工具一行命令全转 Markdown，194k star。 给 agent 喂数据的前置管道，几乎是标配了。 \#中文区 https://t.co/Y47dfx4nen - [Hacker News · currycurry16 · 2026-06-29](https://news.ycombinator.com/item?id=48719833): Jimmy is a tool to convert your notes from different formats to Markdown: Related: https://github.com/microsoft/markitdown - [Bluesky · Toolspire · 2026-10-15](https://bsky.app/profile/toolspire.bsky.social/post/3mxwk6ac4322d): Stop paying $50/mo for document parsing APIs. Microsoft quietly open-sourced MarkItDown (190k+ stars): - Converts PDFs, Excel, Word \& PPTX to Markdown - 1 command execution - 100% free \& local - Token-optimized for LLMs Comment MARK for the instant Python script. toolspirehub.com - [X · @Hiter18ma · 2026-11-07](https://x.com/Hiter18ma/status/2118959240387981484): Your slide screenshot missed the speaker notes. We tested Microsoft's MarkItDown on an original PPTX: the $12,000 budget and a $2,000 note both survived. Slides or PDFs—which do you use more? https://t.co/ZD6F8FeIvg https://t.co/jUIq9Xlf58 ## Get it - [Open microsoft/markitdown on GitHub](https://github.com/microsoft/markitdown) - [Get it on your Mindket account](https://account.mindket.com/account/?product=mindket#/market/d83a05fc-f5ce-49fa-8f49-aaa5ce2a1206) - [Its page on Mindket](https://mindket.com/p/d83a05fc-f5ce-49fa-8f49-aaa5ce2a1206)