安裝指南 · MarkItDown 繁中教學站

1. 建立虛擬環境（推薦）

python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # macOS / Linux

用 uv 更快：uv venv --python 3.12 .venv，之後一律用 uv pip install。

2. 安裝

# 一次裝滿所有格式的依賴（最省事）
pip install 'markitdown[all]'

或者按需安裝，減少體積與攻擊面：

# 只需要 PDF、Word、簡報
pip install 'markitdown[pdf, docx, pptx]'

3. Optional Dependencies（extras）一覽

Extra	啟用的格式/功能
`[all]`	全部選配依賴
`[pptx]`	PowerPoint（python-pptx）
`[docx]`	Word（mammoth + lxml）
`[xlsx]`	Excel .xlsx（pandas + openpyxl）
`[xls]`	舊版 Excel .xls（pandas + xlrd）
`[pdf]`	PDF（pdfminer.six + pdfplumber）
`[outlook]`	Outlook .msg（olefile）
`[az-doc-intel]`	Azure Document Intelligence
`[az-content-understanding]`	Azure Content Understanding
`[audio-transcription]`	音訊轉錄（pydub + SpeechRecognition）
`[youtube-transcription]`	YouTube 字幕（youtube-transcript-api）

4. 從 source 安裝（對齊特定 commit）

git clone git@github.com:microsoft/markitdown.git
cd markitdown
git checkout <commit>                 # 例如 fd239d5（v0.1.7）
pip install -e 'packages/markitdown[all]'

5. Docker

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

6. 周邊套件

# MCP Server（把 markitdown 接上任何 MCP agent）
pip install markitdown-mcp

# OCR 外掛（LLM Vision 抽取 PDF/DOCX/PPTX/XLSX 內嵌圖片文字）
pip install markitdown-ocr
pip install openai   # 或任何 OpenAI 相容 client

7. 驗證安裝

markitdown --version          # 0.1.7
markitdown sample.pdf -o out.md
markitdown --list-plugins     # 列出已安裝的第三方外掛

注意：markitdown 的 --list-plugins 與外掛功能預設關閉，必須安裝外掛套件並用 --use-plugins 或 enable_plugins=True 才會生效。

8. 疑難排解

不支援的格式錯誤：檔案類型未被任何 converter 接受——通常是缺少對應 extras（例如 PDF 沒裝 [pdf]），或真的不支援該格式。
圖片/音訊輸出為空：圖片 EXIF 需要 exiftool（EXIFTOOL_PATH），描述需要 llm_client + llm_model；音訊同理。
音訊轉錄拋 UnknownValueError：SpeechRecognition 聽不懂內容（非語音/無網路/Google API 不可用）——見媒體案例頁。
Windows 中文亂碼：輸出到檔案用 -o（UTF-8），避免 console 編碼問題。
MCP Server 無法連線：確認 markitdown-mcp 在 PATH 上，或改用 Docker 啟動。