MarkItDown 怎麼用：把 PDF、Word、Excel、PPT 轉成 Markdown（安裝、命令行與 Python）

本文根據微軟 MarkItDown 官方倉庫 README 整理，資料核對於 2026-10-11。文中代碼和命令取自官方 README，沒有在本機運行驗證。

適用於誰

• 搜「markitdown 使用」「markitdown 怎麼用」「markitdown 安裝」的人；
• 經常要把 Word、Excel、PPT、PDF 的內容貼給大模型，想要一條命令轉成乾淨文本的人；
• 在寫處理文檔的腳本或智能體，需要一個輕量的「任意文件轉文本」組件的人。

結論先說

1. MarkItDown 是微軟開源的一個輕量 Python 工具，把各種文件轉成 Markdown，用於大模型和文本分析流程。
2. 格式覆蓋很廣：PDF、PowerPoint、Word、Excel、圖片、音頻、HTML、CSV / JSON / XML、ZIP、YouTube 連結、EPub。
3. 安裝：pip install 'markitdown[all]'，需要 Python 3.10 到 3.14。
4. 最常用的一條命令：markitdown 文件 -o 輸出.md。
5. 它以當前進程的權限讀文件。在服務端處理用戶上載的、來源不可信的文件時，要按官方的安全提示限制輸入。

一、為什麼是 Markdown

README 的解釋：Markdown 非常接近純文本，同時又保留了文檔的結構（標題、列表、表格、連結）；主流的大模型對它理解得很好；而且它的寫法很省 token。

也就是說，目標不是做出一份排版精美的文檔給人看，而是給模型一份結構清楚、沒有多餘格式噪聲的輸入。

二、支持的格式

三、安裝

bash
pip install 'markitdown[all]'

[all] 會裝上所有格式需要的依賴。只需要其中幾種時，可以按需選擇，例如：

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

README 列出的可選項有 [pptx]、[docx]、[xlsx]、[xls]、[pdf]、[outlook]、[az-doc-intel]、[audio-transcription]、[youtube-transcription] 等。

Windows 的命令提示符不把單引號當作引號，改用雙引號：pip install "markitdown[all]"。

四、命令行

三種寫法：

bash
markitdown path-to-file.pdf > document.md
markitdown path-to-file.pdf -o document.md
cat path-to-file.pdf | markitdown

• 第一種把結果重定向到文件；
• 第二種用 -o 指定輸出文件；
• 第三種從標準輸入讀取，適合接在管道里。

五、Python 調用

python
from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False) # Set to True to enable plugins
result = md.convert("test.xlsx")
print(result.markdown)

convert 接收文件路徑，返回的結果對象裏 markdown 屬性就是轉換後的文本。

批量轉換一個文件夾，就是遍歷文件、逐個調用 convert、把 result.markdown 寫到同名的 .md 文件裏。

六、讓大模型給圖片寫描述

圖片本身沒有文字時，可以接一個多模態模型來生成描述。README 說明這項功能目前用於 PPTX 和圖片文件：

python
from markitdown import MarkItDown
from openai import OpenAI

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

這會調用模型接口，產生費用，並且圖片內容會發送給模型服務商。處理內部資料前先確認是否允許。

七、插件與 OCR

插件預設是關閉的：

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

README 提到的 markitdown-ocr 插件，給 PDF、DOCX、PPTX、XLSX 的轉換加上基於大模型視覺能力的 OCR，用 pip install markitdown-ocr 安裝。官方說明：沒有提供 llm_client 時，OCR 會被跳過，仍然使用標準的轉換器。

所以掃描版 PDF（每頁是一張圖片）用預設方式轉出來可能是空的或者很少，這時需要 OCR 插件，或者換用帶版面識別的工具，見《Docling 使用教學》。

另外還可以接 Azure 的 Document Intelligence 服務來轉換：

bash
markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"

八、Docker 與 MCP

Docker（在克隆下來的倉庫目錄裏構建）：

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

MCP 伺服器：官方提供了 markitdown-mcp 這個包，即 MarkItDown 的 MCP 伺服器，接入支持 MCP 的客戶端後，智能體可以自己調用它來轉換文件。配置方法見該包的說明；MCP 的基本用法見《Claude Desktop MCP 配置教學》。

九、安全提示

README 的原話是：MarkItDown 以當前進程的權限執行讀寫。並給了兩條建議：

• 對不可信的輸入要先做清理和校驗；
• 只處理本地文件時用 convert_local()；需要對輸入有最大程度的控制時用 convert_stream()。

背景是：它支持的輸入裏既有本地文件也有網址（如 YouTube 連結）。如果你的服務把用戶提交的字符串原樣傳給轉換函數，對方就可能讓你的伺服器去讀取本機文件或訪問不該訪問的地址。做成在線服務時，這一點必須處理。

常見問題

Q：轉出來的 PDF 表格是亂的？

MarkItDown 定位是輕量轉換。表格複雜、雙欄排版、掃描件這類情況，用版面理解能力更強的工具，見《Docling 使用教學》和《MinerU 是什麼》。

Q：ChatGPT、Claude 不是能直接讀 PDF 嗎，還要它幹什麼？

聊天產品裏直接上載確實方便。需要它的場景是：批量處理、寫進自己的程序、導入知識庫之前的預處理，或者想先看看模型實際「讀到」的文本是什麼樣。上載文件的限制見《Claude 文件上載限制》。

Q：命令找不到？

確認是在裝了它的那個 Python 環境裏運行；用虛擬環境的話先激活。也可以用 python -m pip show markitdown 確認是否安裝成功。

Q：能保留圖片嗎？

它的輸出是文本。圖片內容可以通過第六節的方式變成一段文字描述；輸出裏是否保留圖片引用，以官方說明和實際結果為準。

參考資料

• microsoft/markitdown（官方倉庫與 README）：https://github.com/microsoft/markitdown