MarkItDown は Web スクレイパーといっしょくたに語られがちですが、それは誤解です。クローラーも JavaScript 実行環境もなく、URL を取りに行って余計な装飾を削るような仕組みもありません。できるのは、すでに手元にあるデータ――PDF、Word 文書、スプレッドシート、プレゼン資料など――を受け取り、言語モデルが読みやすい Markdown に丸ごと変換することです。
私は Microsoft の MarkItDown を、Mac 1 台で実際の文書群に数週間かけて通し、各テーブルを実行前に作成したマニフェストと突き合わせながら採点し、変換時間も測りました。結論を先に言うと、入力がきれいなら高速で忠実に変換できる一方で、パッケージには自分で入れた覚えのない 73 MB の機械学習ランタイムが含まれ、表は「テキストは残っているか？」には合格しても「データが正しい列に入っているか？」では落ちる壊れ方をします。以下で、数値つきで全体像を見ていきます。
MarkItDown の正体
MarkItDown は Microsoft 製の Python ユーティリティで、ファイルや Office 文書を LLM 向けに最適化した Markdown に変換します。PDF、.docx、.xlsx、.pptx、画像、HTML、その他いくつかの形式を渡すと、Markdown を返してくれます。呼び出し方法は 3 つあり、CLI（markitdown file.pdf -o out.md、または stdin からのパイプ入力）、Python API（MarkItDown().convert(...)）、そしてエージェント向けワークフロー用の MCP サーバーです。
ここでいちばん大事なのは、何をしないかです。README でもそううたっていませんし、私の検証でも確認しましたが、クロール、JS レンダリング、リンク追跡、ページ送り対応、Readability 系の本文抽出はしません。これは文書全体の変換ツールです。あなたがバイト列を持ち込み、それを標準化する。たったこの違いで、ツールをスタックに入れるべきかが決まるので、この点は何度も触れます。
GitHub の見栄え指標で見ると、このリポジトリはかなり大きく、2026 年 7 月中旬時点で 165,282 stars、11,790 forks を持ち、MIT ライセンスで、最新リリースは v0.1.6（2026-05-26）です。ただし、このスター数は Microsoft 系リポジトリに対する LLM ツール熱の反映であって、変換内部の成熟度を直接示すものではありません。未解決 issue は 833 件あり、そのいくつかはインストール前に知っておいたほうがいい内容です（後述）。
HTML→Markdown: 高速で忠実、ただし余計な装飾もそのまま
私のスクレイパーレビュー連載では同じ 4 つの Web フィクスチャを使っているので、MarkItDown にも同じローカル HTML を与えました。スクレイパーとして採点するためではなく、HTML→Markdown 変換の出来を見たかったからです。タグの整ったページでは、かなり優秀です。
4 ページすべてが追加パッケージなしのコア導入だけで変換でき、本文の内容もすべて保持されました。Wikipedia の「Web scraping」記事（226 KB）は、見出し階層がそのまま再現され、h1 が 1、h2 が 7、h3 が 12 で、元のセクション構造にぴったり一致していました。リンクも 418 件すべてが [text](url) として残っています。Scrape This Site の forms ページ にある 26×9 のホッケースタッツ表は、27 行のきれいな GFM パイプ表（ヘッダー＋区切り＋データ 26 行）になり、空欄もそのままでした。速度も悪くなく、小さな quotes ページで中央値 48 ms、226 KB の Wikipedia ページでも 352 ms でした。
ただし、ここには落とし穴があります。これはバグではなく設計です。MarkItDown は余計な装飾を取り除きません。<body> 全体を変換するので、サイトのナビやフッターもそのまま出力され、しかもその残り方はページの装飾量に比例します。
| ページ | 出力文字数 | 見出し (h1/h2/h3) | リンク数 | サイト装飾行 |
|---|---|---|---|---|
| Books to Scrape | 10,478 | 1 / 0 / 0 | 94 | 0.6% (1/159) |
| Quotes to Scrape | 2,973 | 1 / 1 / 0 | 55 | 1.2% (1/86) |
| ScrapeThisSite forms | 3,385 | 1 / 0 / 0 | 31 | 6.7% (5/75) |
| Wikipedia Web scraping | 60,159 | 1 / 7 / 12 | 418 | 12.4% (42/338) |
ほとんど装飾のない Books のホームページでは、出力行の 0.6% しか装飾が含まれません。Wikipedia では 12.4% で、338 行中 42 行が「本文へ移動」「目次の表示/非表示」「22 languages」「retrieved from」「cookie」やライセンスのフッターです。Wikipedia のメンテナンス用バナー（「この記事には追加の出典が必要です」など）まで忠実にパイプ表へ変換されるので、実データ表が存在しないページでも 9 行分の表ができてしまいます。
とはいえ、これは MarkItDown が間違っているわけではありません。これは本文抽出器ではなく、文書全体を忠実に Markdown 化するツールです。忠実な HTML→Markdown と、読みやすい本文抽出は別物です。Trafilatura や Firecrawl 系のツールは本文だけを返すことを目指しますが、MarkItDown はページ全体を返します。内部的には _html_converter.py が <script> と <style> を取り除いたうえで、markdownify に <body> 全体を渡しており、本文抽出のヒューリスティックは一切ありません。記事だけが欲しいなら、このレイヤーは違います。
本来の得意分野: PDF、DOCX、XLSX、PPTX
MarkItDown が本当に作られているのは文書です。私は実在の公開ファイルで試しました。テキストレイヤーを持つ arXiv 論文、Bitcoin ホワイトペーパー、テキストのない画像だけのスキャン PDF（ゼロテキストになるようレンダリング）、そして MarkItDown 自身のテストスイートにある DOCX/XLSX/PPTX ファイル（静かに内容が欠落したか検出するため UUID 付き）です。
| 文書 | 入力サイズ | 出力文字数 | 検証プローブ | 中央処理時間 | 備考 |
|---|---|---|---|---|---|
| arXiv 1706.03762（テキストレイヤー PDF） | 2.2 MB | 40,174 | 7/7 | 3.7 秒（ウォーム） | title、"Transformer"、"BLEU"、"References" を確認 |
| Bitcoin whitepaper（9 ページ PDF） | 184 KB | 22,485 | 6/6 | 1.4 秒 | "Satoshi Nakamoto"、"proof-of-work"、"Conclusion" を確認 |
| スキャン PDF（テキストレイヤーなし） | 89 KB | 0 | 0/4 | 15 ms | 空出力、エラーなし、OCR なし |
| DOCX（test.docx） | 136 KB | 4,651 | — | 70 ms | 見出し＋GFM 表、埋め込み UUID も保持 |
| 数式入り DOCX | 15 KB | 240 | — | 101 ms | Office Math を LaTeX として保持 |
| XLSX（test.xlsx） | 12 KB | 808 | — | 57 ms | 各シート → ## SheetName ＋ GFM 表 |
| PPTX（test.pptx） | 278 KB | 2,047 | — | 52 ms | スライド番号マーカー、表、グラフ→表 |
テキストレイヤー付き PDF のテキスト再現率はかなり高く、arXiv の「Attention Is All You Need」では 7/7、Bitcoin whitepaper では 6/6 の事前登録プローブをすべて通過しました。Office ファイルでも、メンテナ自身の回帰用フィクスチャにある UUID センチネルを 1 つも落とさず、静かな内容欠落はありませんでした。小さくてうれしい勝ち筋として、DOCX の処理経路（mammoth 経由）は Office Math の数式を LaTeX として保持し、equations.docx をちゃんとした $$...$$ 数式に変換します。数式の多い Word 文書を LLM に渡すなら、これは実用的で、しかもあまり語られていない強みです。
この分野で特に注意すべき点が 2 つあります。どちらも、つまずきやすいポイントです。
何も残らず消えるスキャン PDF
テキストレイヤーのない画像だけの PDF を MarkItDown に与えると、空文字列が返ってきます。0 文字、例外なし、警告なし――抽出対象がないので、約 15 ms で終わります。MarkItDown の PDF 経路はテキスト抽出のみで、内部は pdfminer と pdfplumber に依存しており、コア導入にも pip の extras にも OCR は含まれていません。
バッチ処理ではこれが問題になります。PDF が混ざったフォルダを処理している開発者は、スキャン文書だけが静かに空出力になり、何が飛ばされたのか分かりません。念のため、pdfminer の extract_text を直接当ててフィクスチャが壊れていないことも確認しましたが、取り出せるテキストは 0、テキストレイヤーなし、つまり本当にスキャンだけの PDF でした。空出力は MarkItDown の実際の挙動です。これは長く未解決の OCR フォールバック欠如（#1268） の再現でもあります。文書化されている対処法は、任意の Azure Document Intelligence バックエンドかプラグインですが、どちらもデフォルト導入には含まれません。
PDF は構造ではなく平坦なテキストとして出てくる
テキストレイヤー付き PDF を 2 つ試したどちらでも、MarkItDown は Markdown の見出し記号を 1 つも出しませんでした。PDF には意味的な見出しタグがないため、MarkItDown はフォントサイズから推定もしません。その結果、すべての行が本文レベルに落ちます。テキスト再現率は高いですが、構造は平坦です。
これは私だけの結果ではありません。第三者の公開ベンチマークでは、MarkItDown の PDF 見出し階層スコアはおよそ 0.0、表の忠実度は約 0.27 で、Docling の TableFormer ベースの 0.88 を大きく下回っています（MarkItDown vs Docling vs Marker の比較 と READoc ベンチマーク を参照）。私のフィクスチャは彼らの結果を再現しており、これは証拠としてかなり強いです。外部ソースと数字が一致しています。同じベンチマークが示すトレードオフは、MarkItDown が Docling より約 100 倍速いことです。これは、レイアウトモデル系のツールが数分かける文書を、私の計測でも数秒で処理したことと一致します。要するに、MarkItDown がくれるのはきれいで高速な PDF のテキストであって、PDF の構造ではありません。見出しや表の保持が必要なら、Docling や Marker のようなレイアウトモデル系ツールが向いています。
表: テキストは残る、構造は時々壊れる
表の世界では、「テキストは残ったか？」と「データとして使えるか？」が分かれます。そこで私は 13 ケースのマトリクスを作り、各ケースに対して実行前に書いたマニフェストと照合しながら、どの形状が保たれ、どこが壊れるのかを正確に記録しました。
結論は明快です。MarkItDown は表の内容を一度も失いませんでした。13 ケースすべてで、事前登録したトークンは 100% 保持されています。ただし、構造の忠実度は 3 通りに分かれました。13 件中 7 件は、きれいな GFM グリッドになりました（単純表、header-colspan、24 列の広い表、ヘッダーなし、空セル、セル内ブロック、右から左のアラビア語）。4 件は崩れました。Markdown にはスパン付きセルの概念がないため、rowspan、colspan、そして壊れたソースは短い行を出してしまいます。そして 2 件は完全に壊れていました。
壊れ方の 2 つは名前を挙げる価値があります。ネストした表（<td> の中に <table> があるもの）はインラインに潰され、内側のパイプ記号と区切り行が親セルに流れ込んで、14 列のゴミ行を作ります。さらに、セル内のリテラルな | はエスケープされません。a | b は 2 列になり、x || y は 3 列になってしまうため、2 列表なのに 2 列・3 列・4 列の行が混ざり、後段の Markdown パーサーは誤った境界で読みます。おもしろいことに、セル内のアスタリスクやバッククォートはエスケープされますが、パイプだけはされません。原因は、MarkItDown の HTML 経路が markdownify の標準テーブル処理を使っており、独自サブクラスはリンク、画像、見出しだけを上書きしていて、セルは上書きしていないためです。同じパイプのエスケープ不備は CSV 変換器の open issue (#2019) でも見られますが、その修正は今回触れた HTML 経路には影響しません。
細かながら、データエンジニアにぜひ見てほしいのが rowspan です。t03 は単に崩れるだけではなく、データを静かにずらします。rowspan=2 のラベル（"Fruit"）は 1 回だけ出力され、その下の行は短い 2 列の行（| Banana | 8 |）になるため、"Banana" は Item 列ではなく Group 列に入ってしまいます。トークン自体はすべて存在しますが、雑に「2 列目を読む」処理は誤った値を取ります。これは、テキストが残っているかのチェックは通ってしまうのに、データセットを静かに壊すタイプのバグです。
このスパン制約自体は既知の設計上の制約で、追跡中です（#1211、#1248）。平坦な GFM パイプ表ではスパンや入れ子を表現できないため、変換器は構造を犠牲にして内容の完全性を優先しています。一方で良い挙動もあります。ヘッダーのない表には空のヘッダー行が合成されるので、データが静かにヘッダー扱いになることはありません。空セルは保持され、<caption> は表の上のテキスト行として残ります。
インストールと起動: 「軽量ユーティリティ」が教えてくれないコスト
ここでいちばん驚いたのはこの部分で、「軽量な Python ユーティリティ」という説明が、実はかなり楽観的だったことが分かります。
まず、pip install 'markitdown[all]' は使わないでください。Python 3.14 では、これが静かに markitdown 0.0.2 まで巻き戻ります。2 年前のリリースです。私はクリーンな venv で実際に再現しました。原因はピン留めを確認すると分かります。pip install 'markitdown[all]==0.1.6' は失敗します。[all] extra が youtube-transcript-api~=1.0.0 を固定しているのに、PyPI 上ではその範囲のビルドはすべて Python <3.14 に制限され、3.14 対応ビルドだけがその pin の外にあるからです。その結果、resolver は依存条件を満たせる最後のリリースまで戻ってしまいます。これは upstream の issue (#2179) と一致します。回避策は単純で、バージョンを固定し、extras を個別に入れることです。pip install 'markitdown==0.1.6' のあとに pip install 'markitdown[pdf,docx,pptx,xlsx,xls]==0.1.6' を入れます。これらはそれぞれ問題なく解決します。毒になっているのは [all] のバンドルだけです。（この罠は Python バージョン依存です。Python 3.13 以前では gate に引っかからず、[all] の解決結果が変わる可能性があります。）
次にフットプリントです。コア導入だけで 161 MB あります（13 MB の空の venv に 148 MB が追加される計算）。そのうち onnxruntime が 73 MB、numpy が 34 MB で、合わせて 107 MB、つまりコア全体の 66% を占めています。そしてこの 2 つは、単一のハード依存である magika――Google の ML ベースのファイル種別検出器――によって引っ張られています。つまり、テキスト変換ツールの基本導入に、文書用 extras を 1 つも追加する前から 73 MB の ONNX 推論ランタイムが入っているわけです。文書 extras を追加すると、venv は 310 MB に達します。これは headless browser スタックよりはずっと軽いですが、「pip install して終わり」の小物ユーティリティを想像していたなら、ONNX ランタイムが一緒に乗ってくると知っておくべきです。
3 つ目は、この調査全体で私が行った novelty チェックをすべて通過した結果です。クリーンインストール後であっても、import markitdown にはこのマシンで約 3.35 秒 かかりました。コストのほとんどは import 時に発生しています。markitdown._markitdown がコンバータ登録を丸ごと eager load しており（累計 2.56 秒、全体の 76%）、それによって pandas（594 ms、XLSX コンバータ経由）、python-pptx（427 ms）、magika（354 ms）、requests（270 ms）が、実際にその形式を変換するかどうかに関係なく読み込まれます。長寿命のサービスなら、この import は一度きりのコストでほぼ気になりません。しかし CLI の 1 回実行やサーバーレスのコールドスタートでは、これは明確な per-process コストであり、「軽量ユーティリティ」というラベルからは想像しにくいものです。（公平に言うと、これは 1 回のプロファイル結果であり、複数回の分布ではなく 1 観測として扱っています。）
スケール: 落ちないが、PDF には CPU 予算を、スプレッドシートには RAM 予算を見ておくべき
私は 4 つの大きな対象を、それぞれ別プロセスで通しました。これにより、ピークメモリが前回実行の残り香で汚れないようにしています。クラッシュは一切ありませんでした。ただし、コストの出方はかなり偏っています。
| 対象 | 入力サイズ | 出力文字数 | 中央時間 | ピーク RSS 増加 |
|---|---|---|---|---|
| NIST SP 800-53r5（492 ページ PDF） | 5.9 MB | 1,625,365 | 192.5 秒 | +40 MB |
| XLSX 50,000 行 × 8 列 | 2.1 MB | 3,722,955 | 62.1 秒 | +374 MB |
| arXiv 1706.03762（約 15 ページ PDF） | 2.2 MB | 40,174 | 12.6 秒 | +25 MB |
| XLSX 200 行 × 64 列 | 46 KB | 120,129 | 2.9 秒 | +22 MB |
492 ページの NIST PDF は中央 192.5 秒、つまり約 3.2 分、1 ページあたり 0.39 秒でした。これは pdfplumber が各ページで word-position ベースのフォーム検出を行うためです。ピーク RSS は +40 MB にとどまっており、メモリより CPU がボトルネックです。15 ページの arXiv PDF でさえ、独立プロセスでは 12.6 秒かかりました。これは同じファイルを文書群の中で warm に処理した 3.7 秒の約 3.4 倍です。この差がコールドプロセスのコストであり、単純なバイトサイズではなくページごとの処理が支配的であることを示しています。この PDF の単一の転用可能な数値としては、独立実行の 12.6 秒を使うのが適切です。
一方で、スプレッドシート側はボトルネックが逆転します。2.1 MB、5 万行の XLSX は、ピーク RSS が +374 MB まで膨らみ（出力文字数は 370 万超）、コンバータがシート全体を読み込み、巨大な Markdown 文字列を 1 つ作るためです。実務上の目安ははっきりしています。大きい PDF には数分の CPU 予算を、大きいスプレッドシートには数百 MB の RAM 予算を見てください。これは macOS arm64 と Python 3.14 での単一マシン計測で、ページあたり・行あたりの定数は環境依存ですが、形としては共通です（PDF は遅くて CPU 依存、XLSX はメモリを食う、クラッシュはしない）。
Thunderbit が適する場面、適さない場面
ここは盛りすぎると危ない比較なので、線引きを慎重にします。MarkItDown と Thunderbit は隣接する問題を解くツールであって、同じ問題を解くわけではありません。
MarkItDown は、すでに手元にあるファイルを変換します。Thunderbit は、まずページを取得します。Thunderbit の /distill エンドポイント は、ライブの Web ページを LLM 向けのきれいな Markdown に変換し、MarkItDown にはない JS レンダリング、bot 対策、動的コンテンツを扱えます。一方 /extract エンドポイントは、ただの Markdown ではなく、スキーマに一致した構造化 JSON を返します。開発者向けには、1 つの AI エンジンの上に API（POST /distill / POST /extract）、MCP サーバー、CLI（npx @thunderbit/thunderbit-cli）として公開されており、これは 10 万人超のユーザーを持つ拡張機能 と同じエンジンです。
つまり、両者が重なるのはたった 1 点、どちらも「LLM-ready Markdown」を出せることだけです。しかし入力ドメインが違います。Thunderbit の distill はオープン Web 上の URL を扱い、MarkItDown はローカルファイルを扱います。代替品ではありません。現実的なスタックは両方を使うことです。Thunderbit（または Firecrawl 系のサービス）で Web を取得・クロールし、同時に手元にある PDF、スライド、スプレッドシートなどのローカル文書を MarkItDown で正規化する。片方はネットワークを、もう片方はファイル棚を担当します。
長所と短所
強み
- きれいな HTML では本文を 100% 回収（4/4 ページ）、見出し階層とリンクも忠実に保持
- PDF/DOCX のテキスト再現率が高い（arXiv 7/7、Bitcoin 6/6）うえ、メンテナ自身の Office フィクスチャで静かな内容欠落なし
- Office Math の数式を LaTeX として保持できる、実用的なニッチ強み
- 492 ページ PDF と 5 万行 XLSX まで、どの規模でもクラッシュしなかった
- 呼び出しが簡単：CLI、
convert()、stdin パイプ、任意の MCP サーバー - MIT ライセンス、Microsoft が積極的に保守、issue 対応も比較的活発
弱み
- 余計な装飾を残す――Wikipedia では最大 12.4% が装飾行で、記事抽出器ではない
- 表はスパン、ネスト、セル内パイプで崩れる（2/13 が壊れ、4/13 が崩れた形に）うえ、rowspan は静かに列をずらす
- スキャン／画像のみ PDF は OCR なし・エラーなしで空出力
- PDF 出力には見出し構造がゼロ（公開ベンチマークとも一致）
- コア導入が 161 MB、73 MB の ONNX ランタイムを同梱、コールド import は約 3.35 秒
[all]extra は Python 3.14 で 2 年前の 0.0.2 へ静かに戻る
どんな人に向いていて、どんな人には向かないか
LLM パイプライン向けに、Word、Excel、PowerPoint、テキストレイヤー付き PDF が混在したローカル文書群を Markdown にそろえたいなら、MarkItDown は有力です。構造の保持よりも、テキストを丸ごと残すことを重視するなら特に向いています。バッチ処理の最後の変換役として、モデルにきれいなテキストを渡す用途では、高速で忠実、しかも無料です。
逆に、次のような仕事なら単独では不十分です。Web ページから本文だけが欲しいなら、readability 系か Firecrawl 系のツールを使ってください。PDF の見出しや表をそのまま残したいなら、Docling か Marker の領域です。入力に OCR が必要なスキャン文書が含まれるなら、Azure backend か別ツールが必要です。そして、もしあなたが探していたのが「取得してクロールする」スクレイパーなら、これはまったく別物です。
私がスクレイパー風の評価軸で provisional に採点すると、MarkItDown は 60/100 です。ただしこの低さは、コンバータをクローラーのテストで採点したことによる見かけ上のものです。本来の土俵ではテキスト忠実度は高く、弱点は構造（表、PDF 見出し）とパッケージング（フットプリント、import、[all] の罠）にあります。あくまで「ファイル→Markdown 変換ツール」として見れば、運用前に知っておくべきいくつかの尖った点はあるものの、堅実でよく保守されたツールです。
よくある質問
MarkItDown は Web スクレイパーですか？
いいえ。クローラー、JavaScript レンダリング、リンク追跡、ページ送り対応はありません。すでに手元にあるファイルや文書――PDF、DOCX、XLSX、PPTX、画像、HTML――を Markdown に変換するツールです。ライブの Web ページを取得してクロールしたいなら、Thunderbit や Firecrawl のようなスクレイピングツールが必要です。MarkItDown はその後段で、取得済みまたはローカルのファイルをきれいな Markdown に整える役割です。
なぜ pip install markitdown[all] で古いバージョンが入るのですか？
Python 3.14 では、[all] extra が youtube-transcript-api~=1.0.0 を固定しており、その範囲のビルドはすべて Python 3.14 未満に制限されています。resolver はその pin を満たせないため、静かに markitdown 0.0.2 まで戻ってしまいます。対処法は、バージョンを固定して extras を個別に入れることです。pip install 'markitdown==0.1.6' のあとに 'markitdown[pdf,docx,pptx,xlsx,xls]==0.1.6' を追加します。これは issue #2179 として追跡されています。
MarkItDown はスキャン PDF に OCR を使いますか？
デフォルト導入では使いません。PDF 経路はテキスト抽出のみなので、テキストレイヤーのない画像だけの PDF は空文字列になります。エラーも警告も出ません。OCR には任意の Azure Document Intelligence backend かプラグインが必要で、どちらも標準では含まれていません。これは長く追跡されているギャップです（issue #1268）。
MarkItDown は表をどの程度うまく処理しますか？
内容面ではかなり優秀で、私の 13 ケーステストではすべてのケースで表の内容を 100% 保持しました。構造面は形によります。単純表、横に広い表、ヘッダーなし表、空セル表はきれいな GFM グリッドになりますが、rowspan と colspan は崩れやすく、rowspan はデータを静かに誤った列へずらすことがあります。ネストした表はゴミ行に潰れ、セル内のリテラルなパイプ文字はエスケープされません。Markdown の平坦な表形式では、スパンや入れ子を表現できないからです。
MarkItDown は大きな文書にも十分高速ですか？
大きなファイルでクラッシュはしませんが、種類ごとにリソースの見積もりが必要です。492 ページの PDF は、ページごとのフォーム検出を行うため約 3.2 分（およそ 0.39 秒/ページ）かかり、CPU ボトルネックです。5 万行のスプレッドシートは約 1 分で終わりますが、1 つの大きな Markdown 文字列をメモリ上で組み立てるため、RAM を +374 MB 消費しました。大きな PDF なら CPU を数分、大きなスプレッドシートなら RAM を数百 MB 見ておくのが実務的です。
Web データ抽出に Thunderbit を試す Get Started Free
