Microsoft MarkItDown 使用笔记

2. Basic Information

Examination date: 2026-08-06. Version, Star, Release and dependency version may change. It is recommended to look at PyPI or GitHub Release before formal use.

3. What is suitable

4. Not suitable for what to do

1. Not suitable for high fidelity format conversion. For example, Word style, header and footer, paging, font, layout should be completely retained, you should find a special document layout/conversion tool.
2. It is not suitable to handle untrusted input without filtering. The official security instructions emphasize that the MarkItDown will perform I/O with the permissions of the current process and can access local files and network resources that the current process can access.
3. Not suitable for direct exposure to public network services. In particular, the "markitdown-mcp" HTTP/SSE mode, the official clearly suggested that only localhost should be bound by default, not to the external network address casually.
4. It is not suitable to expect a conversion to get the perfect knowledge base notes. It is responsible for extraction and conversion, and subsequent title reorganization, summary, terminology interpretation, picture screening, and manual proofreading still need to be done.
5. It is not suitable to put all formats into the production environment after pretending to be the most dependent. In production, it is recommended to install optional dependencies in the format to reduce the attack surface and dependency conflicts.

5. Supported input formats

The official README mentions current support:

-PDF

-PowerPoint

-Word

-Excel

-Image: EXIF metadata and OCR/image description related capabilities

-Audio: EXIF metadata and voice transcription

-HTML

-Text formats: CSV, JSON, XML

-ZIP file: traverses the contents

-YouTube URLs

-EPubs

-Other formats

From PyPI and 'pyproject.toml', the core dependencies include 'beautifulsoup4', 'requests', 'markdownify', 'magika', 'charset-normalizer, and 'defusedxml '. Different formats are unlocked by optional dependencies.

6. Installation and dependencies

Basic requirements

MarkItDown requires Python 3.10 or higher. It is officially recommended to use a virtual environment to avoid dependency conflicts with system Python or other projects.

Ordinary venv:

python -m venv .venv
source .venv/bin/activate

With 'uv ':

uv venv --python=3.12 .venv
source .venv/bin/activate
uv pip install 'markitdown[all]'

With conda:

conda create -n markitdown python=3.12
conda activate markitdown

Install from PyPI

the most convenient way to install:

pip install 'markitdown[all]'

Only partial format dependencies are installed:

pip install 'markitdown[pdf,docx,pptx]'

Install from source:

git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

7. How to choose optional dependencies

My suggestion: try it on a personal computer directly '[all]'; Put it in the project or server, it is best to install it according to the actual file type. For example, if you only process Office PDF, install '[pdf,docx,pptx,xlsx]', and there is no need to bring audio, YouTube and Azure related dependencies.

8. CLI Quick Start

Most common commands:

markitdown path-to-file.pdf > document.md

Specify the output file:

markitdown path-to-file.pdf -o document.md

Pipe Input:

cat path-to-file.pdf | markitdown

When working with batch processing, I prefer to explicitly write the output path to facilitate subsequent inspection:

markitdown 客户方案.pdf -o 客户方案.md
markitdown 需求说明.docx -o 需求说明.md
markitdown 产品介绍.pptx -o 产品介绍.md
markitdown 数据表.xlsx -o 数据表.md

9. Python API Usage

Basic Usage:

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.text_content)

If you only need to convert local files, it is more recommended to use a narrower API for security. According to the official security instructions, 'convert()' is relatively loose and can handle local files, remote URI and byte streams. If only local files are processed, convert_local() is preferred. If you need to control your own network requests, you can first use 'requests.get()' and then give the response to' convert_response()'; If you want maximum control, open stream and use' convert_stream()'.

Intelligence with Azure Document:

from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="")
result = md.convert("test.pdf")
print(result.text_content)

Generate a description for a picture or an image in PPTX:

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="optional custom prompt",
)
result = md.convert("example.jpg")
print(result.text_content)

10. Plugin Mechanism

MarkItDown supports third-party plugins, but is turned off by default.

List installed plug-ins:

markitdown --list-plugins

To enable plug-in conversion:

markitdown --use-plugins path-to-file.pdf

Enabled in Python:

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=True)
result = md.convert("path-to-file.rtf")
print(result.text_content)

The official repository contains 'packages/markitdown-sample-plugin. It shows how to customize 'DocumentConverter', register 'register_converters()', and expose the plug-in through 'markitdown.plugin' entry point of 'pyproject.toml.

11. OCR Plugin

There is a markitdown-ocr plug-in in the warehouse, the goal is to extract text from images embedded in PDF, docx, PPTX and XLSX. It reuses MarkItDown existing llm_client/llm_model mode without introducing additional local OCR large models or binary dependencies.

Installation:

pip install markitdown-ocr
pip install openai

Command line use:

markitdown document.pdf --use-plugins --llm-client openai --llm-model gpt-4o

Using Python:

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)

result = md.convert("document_with_images.pdf")
print(result.text_content)

Several key points:

-PDF: embedded images can be extracted; scanned PDF will be rendered into images by page and handed over to LLM Vision.

-docx: inserts OCR text blocks in the document stream, preserving context as much as possible.

-PPTX: Process picture shape, placeholder picture, group picture.

-XLSX: Pictures are listed in the 'Images in this sheet' area after the worksheet data.

-The output OCR block is wrapped in '[Image OCR] ... [End OCR].

-If no llm_client or llm_model is passed, the plug-in will load, but OCR will skip and fall back to the built-in converter.

This is very practical: the key content in many customer profiles is actually screenshots, scanned pages or PPT pictures. Ordinary text extraction will leak, OCR plug-in can make up a piece. However, it will call LLM Vision, which means there are API costs, data exit and privacy compliance issues.

12. Azure Content Understanding

The README specifically covers the Azure Content Understanding. It is suitable for scenarios that require higher quality parsing, structured field extraction, and multi-modal processing.

Installation:

pip install 'markitdown[az-content-understanding]'

CLI:

markitdown path-to-file.pdf --use-cu --cu-endpoint ""

Python:

from markitdown import MarkItDown

md = MarkItDown(cu_endpoint="")
result = md.convert("report.pdf")
print(result.markdown)

Specify custom analyzer:

md = MarkItDown(
    cu_endpoint="",
    cu_analyzer_id="my-invoice-analyzer",
)
result = md.convert("invoice.pdf")
print(result.markdown)

For Understanding with Azure Content:

-Scan PDF, complex tables, multi-page documents, built-in conversion effect is not enough.

-Structured fields need to be extracted from invoices, receipts and contracts.

-To handle audio, video and other multi-modal files.

-Already in Azure environment, can accept API call cost and data compliance path.

Cost Alert: Every time you go 'convert()'of a CU is an Azure API call. You can use "cu_file_types" to limit which formats go to CU to prevent all files from going to the cloud by mistake.

13. Azure Document Intelligence

If you only want to use Azure Document Intelligence for document conversion:

markitdown path-to-file.pdf -o document.md -d -e ""

Python:

from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="")
result = md.convert("test.pdf")
print(result.text_content)

Compared with Azure Content Understanding, Document Intelligence is more biased towards document layout analysis. Content Understanding covers more modalities and can extract structured fields through analyzer.

14. MCP Server

markitdown-mcp is a MarkItDown MCP server package that is suitable for local trusted agents. It exposes a tool:

convert_to_markdown(uri)

'uri' can be 'http:', 'https:', 'file:'or 'data:' URI.

Installation:

pip install markitdown-mcp

Default STDIO startup:

markitdown-mcp

HTTP/SSE mode:

markitdown-mcp --http --host 127.0.0.1 --port 3001

Docker:

docker build -t markitdown-mcp:latest .
docker run -it --rm markitdown-mcp:latest

If you want to access local files, you need to mount the directory:

docker run -it --rm -v /home/user/data:/workdir markitdown-mcp:latest

Security alerts are important: the MCP server is not authenticated and will run with the privileges of the user that started it. The HTTP/SSE default binding localhost is for a reason. Don't bind it to '0.0.0.0 'exposed to LAN or public networks unless you are clear about file read and network access risks and do sandbox isolation.

15. Docker Usage

The main repository also supports Docker:

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

The advantage of Docker is dependency isolation, which is especially suitable for batch conversion of files in the server or CI. The disadvantage is that local file access requires a directory to be mounted, and some scenarios that require cloud APIs, audio processing, or plug-ins require additional configuration of environment variables and dependencies.

16. Match with Obsidian

MarkItDown is very suitable for the first step of Obsidian data import.

Recommended process:

1. Put the original PDF/PPT/Word/Excel into the data catalog.
2. Use the MarkItDown to transfer out the Markdown.
3. Manually or with Agent for secondary finishing: supplement title, abstract, label, source, picture description and key conclusion.
4. Put in the Obsidian '07-Learning Materials 'or specific project directory.

Example:

markitdown 客户材料.pdf -o 客户材料.raw.md

Then let the agent organize:

-'Customer Material Summary. md'

-'Customer Issue List. md'

-'Key points of technical solution. md'

-'Matters to be confirmed. md'

Don't just take all the conversion results as final notes. The conversion results are more like raw materials, and the real value in the Obsidian is the structured notes after finishing.

17. Match with RAG/Knowledge Base

When RAG is put into storage, MarkItDown can undertake the step of "format normalization.

A common process:

原始文件 -> MarkItDown 转 Markdown -> 清洗/分块 -> 向量化 -> 入库 -> 检索问答

It is more controllable than throwing the PDF binary directly to the model, because the title, list, table, and link are retained in the Markdown, and it is easier to cut by chapter and paragraph when subsequent blocks are divided.

But pay attention:

-The quality of table conversion should be sampled and checked.

-PDF header footer may generate noise.

-The scanned document requires OCR. Don't expect ordinary PDF extraction to get the text.

-The converted Markdown should be de-duplication, chunky and supplemented with metadata.

-Sensitive materials should not go directly to the cloud OCR or external LLM Vision.

18. Typical usage scenario

19. FAQ with Pit

20. Safety Precautions

The official README security reminder is worth noting separately: the MarkItDown will perform I/O with the current process permissions, similar to' open()'or' requests.get()', and can access resources that the current process can already access.

If you convert your own data on a local PC, the problem is usually not great. However, once it is placed in the Web service, enterprise background and Agent automation platform, it is necessary to carefully control the input:

-Restrict the accessible local directory and do not allow users to pass 'file:///'.

-Restrict the URL scheme to allow only 'https' or whitelisted domains.

-Block access to intranet address, loopback, link-local, metadata service.

-Limit the type, size and compression level of uploaded files.

-Use narrower APIs like 'convert_local()', 'convert_stream()', 'convert_response().

-Do native binding, container isolation, and least privilege running on the MCP server.

It's not a big deal. Once the document conversion tool can read files, access URLs, and decompress ZIP, there are natural risks such as file reading, SSRF, compressed package bombs, and sensitive information leakage.

21. Maintaining State and Ecology

MarkItDown maintenance signal is very strong:

-GitHub Star is very high and has great attention.

-The latest Release is 2026-07-29 'v0.1.7'.

-Recent code push also at 2026-07-29.

-PyPI package syncs to '0.1.7 '.

-The repository contains the main package, MCP server, OCR plug-in, sample plug-in.

-Adopts MIT License, suitable for use in commercial and internal projects, but still subject to the license text and Microsoft trademark statement.

But also see that it is still marked as Beta. In production projects, don't skip testing just because it's a Microsoft warehouse. At least prepare a set of your own sample documents: PDF, scanned documents, PPT, forms, contracts, pictures mixed materials, and see the output effect category by category.

22. The value of pre-sales work

The most immediate value of MarkItDown to pre-sales is not "selling a conversion tool to the customer", but making data processing smoother.

Before sales, customers often receive PDF, PPT, Word, Excel and screenshot packages. Manual reading is very slow, directly thrown to the large model and easy to super-context, throw structure, file format is not compatible. MarkItDown can first turn the material into a Markdown, and then let the model do:

-Demand point extraction

-Business process combing

-Technical Architecture Summary

-List of risks and items to be confirmed

-PPT outline generation

-RAG knowledge base pre-processing

-Draft project delivery document

In customer communication, we can say this: instead of just "uploading files to the model", we first unify multi-format materials into retrievable, chunkable, traceable source text, and then enter the knowledge base or Agent process. MarkItDown can be used as one of the lightweight conversion components.

23. My usage suggestion

Personal learning and Obsidian data collation: directly install' [all]'and run with CLI first.

Project PoC: install dependencies by file type, keep the original file and converted Markdown, and sample check tables, page numbers, title levels, and picture text.

Enterprise production: put MarkItDown in sandboxes or containers, restrict input paths and network access. Scans, tickets, complex forms don't just rely on default conversion, evaluate OCR or Azure Content Understanding in advance.

Match with Agent: MCP server is preferred for local trusted Agents. Be very cautious in public network scenarios. The safest way is to let the server control the file download and permissions, and then give the stream to the MarkItDown instead of letting the user enter any URI.

24. References

-GitHub repository:microsoft/markitdown

-PyPI:markitdown

-Main package configuration:packages/markitdown/pyproject.toml

-MCP server:packages/markitdown-mcp

-OCR plugin:packages/markitdown-ocr

-Sample plugin:packages/markitdown-sample-plugin

-Latest Release:v0.1.7

-Azure Content Understanding:Microsoft Learn

-Azure Document Intelligence:Microsoft Learn

-Safety Report:MSRC