本サイトでは、文章の一部の生成系AIを活用しています。また、一部の記事にはアフィリエイトリンクを設定しています。

はじめに

生成AIにWord資料を読ませたいとき、.docx をそのまま渡せないため、事前にテキストへ変換する必要があります。

Pythonでこれをやる定番ライブラリが markitdown と python-docx です。
この記事では、同じ sample.docx を両方で解析して、何が取れて何が取れないのかを比較しました。

markitdownとは

markitdown は、Microsoftが公開しているPython製のOSSで、さまざまなファイルをMarkdownに変換するツールです。

  • PDF、Word、Excel、PowerPoint、HTMLなど、多くの形式に対応
  • 見出し・リスト・表といった文書の構造をMarkdownとして残す
  • コマンドライン(markitdown sample.docx)でも、Pythonコードからでも使える
  • 生成AI(LLM)に文書を読ませる前処理として使う用途を想定している

Wordの変換には内部で mammoth というライブラリが使われます。
Markdownはトークン数が少なく、LLMが扱いやすい形式です。そのため、RAGやAIエージェントの入力準備でよく使われます。

python-docxとは

python-docx は、Wordファイル(.docx)を読み書きするためのPythonライブラリです。

  • 段落・表・ヘッダー/フッター・コメントなどをPythonのオブジェクトとして扱える
  • 既存のdocxの読み取りだけでなく、文書の新規作成や編集もできる
  • 見出しスタイル・フォント・太字・斜体なども操作できる
  • 対応するのはdocxのみ(PDFやExcelは扱えない)

markitdownが「変換ツール」なのに対して、python-docxは「docxを操作するための部品」です。
テキストを取り出すには、段落や表を自分でたどるコードを書く必要があります。

2つのツールの概要

項目 markitdown python-docx
バージョン(検証時) 0.1.9 1.2.0
提供元 Microsoft(作者 Adam Fourney) Steve Canny
ライセンス MIT MIT
出力形式 Markdown(テキスト) Pythonオブジェクト(自分でテキスト化する)
入力形式 PDF / Word / Excel / PowerPoint / HTML など docxのみ
書き込み 不可(変換専用) 可(文書の作成・編集もできる)

検証方法

次のスクリプト(compare_docx.py)で、同じdocxを両方の方法で解析しました。全文は次のとおりです。

"""Word(docx)の解析を python-docx と markitdown で行い、結果を比較するサンプル。

使い方:
    python compare_docx.py sample.docx --out-dir out
"""

import argparse
from pathlib import Path

from docx import Document
from lxml import etree
from docx.document import Document as DocumentType
from docx.oxml.ns import qn
from docx.table import Table
from docx.text.paragraph import Paragraph

from markitdown import MarkItDown


def _iter_block_items(doc: DocumentType):
    """本文の段落と表を文書内の出現順で返す。

    ``doc.paragraphs`` と ``doc.tables`` は別々に取得されるため順序が失われる。
    body の子要素を直接走査して元の順序を保つ。

    Args:
        doc: python-docx の Document。

    Yields:
        Paragraph または Table。
    """
    for child in doc.element.body.iterchildren():
        if child.tag == qn("w:p"):
            yield Paragraph(child, doc)
        elif child.tag == qn("w:tbl"):
            yield Table(child, doc)


_NS = {
    "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
    "wps": "http://schemas.microsoft.com/office/word/2010/wordprocessingShape",
    "a": "http://schemas.openxmlformats.org/drawingml/2006/main",
    "c": "http://schemas.openxmlformats.org/drawingml/2006/chart",
    "dgm": "http://schemas.openxmlformats.org/drawingml/2006/diagram",
    "r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
}


def _xp(el, expr: str):
    """名前空間付きで XPath を評価する。"""
    return etree.XPath(expr, namespaces=_NS)(el)


def _drawing_lines(p: Paragraph) -> list[str]:
    """段落内の図形(テキストボックス・オートシェイプ・グラフ・SmartArt)を行にする。

    python-docx にはこれらの API が無いため XML を直接読む。

    - テキストボックス/オートシェイプ: ``wps:txbx`` 内の段落テキスト。
      mc:Fallback(VML)側は ``wps`` ではないため二重取得にならない。
    - グラフ: ``c:chart`` の関連パートからカテゴリと系列の値。
    - SmartArt: ``dgm:relIds`` の dm 関連パート(dataN.xml)内の ``a:t``。

    Args:
        p: 対象の段落。

    Returns:
        解析結果の行リスト(図形が無ければ空)。
    """
    lines = []
    for tx in _xp(p._p, ".//wps:txbx"):
        text = "\n".join(
            "".join(t.text or "" for t in para.iterfind(".//w:t", _NS))
            for para in tx.iterfind(".//w:p", _NS)
        )
        lines.append(f"    [TEXTBOX/SHAPE] {text!r}")
    for ch in _xp(p._p, ".//c:chart"):
        rid = ch.get(f"{{{_NS['r']}}}id")
        root = etree.fromstring(p.part.related_parts[rid].blob)
        for plot in _xp(root, ".//c:plotArea/*[c:ser]"):
            cats = [v.text for v in _xp(plot, "c:ser[1]/c:cat//c:pt/c:v")]
            lines.append(f"    [CHART {etree.QName(plot).localname}] categories: {cats}")
            for ser in _xp(plot, "c:ser"):
                name = _xp(ser, "c:tx//c:v/text()")
                vals = [float(v) for v in _xp(ser, "c:val//c:pt/c:v/text()")]
                lines.append(f"      series {name[0] if name else None!r}: {vals}")
    for rel in _xp(p._p, ".//dgm:relIds/@r:dm"):
        root = etree.fromstring(p.part.related_parts[rel].blob)
        # 1 項目が複数ランに分かれる(例: "項目" + "A")ため、段落(a:p)単位で連結する。
        texts = [
            "".join(t.text or "" for t in para.iterfind(".//a:t", _NS))
            for para in _xp(root, ".//dgm:pt//a:p")
        ]
        texts = [t for t in texts if t]
        lines.append(f"    [SMARTART] {texts!r}")
    return lines


def _describe_paragraph(p: Paragraph) -> str:
    """段落を「スタイル名 + 本文 + 書式付きラン情報」の 1 行にする。

    Args:
        p: 対象の段落。

    Returns:
        解析結果の 1 行。
    """
    extras = []
    # 太字・斜体・ハイパーリンクなど、Markdown 変換で差が出やすい要素を併記する。
    if any(r.bold for r in p.runs):
        extras.append("bold")
    if any(r.italic for r in p.runs):
        extras.append("italic")
    if p._p.findall(qn("w:hyperlink")):
        extras.append("hyperlink")
    if p._p.findall(".//" + qn("w:drawing")):
        extras.append("image")
    suffix = f" <{','.join(extras)}>" if extras else ""
    return f"- [P:{p.style.name}] {p.text!r}{suffix}"


def _describe_table(t: Table) -> list[str]:
    """表を行ごとのセルテキストとして返す。

    Args:
        t: 対象の表。

    Returns:
        解析結果の行リスト。
    """
    lines = [f"- [TABLE] {len(t.rows)}x{len(t.columns)}"]
    for r, row in enumerate(t.rows):
        lines.append(f"    row{r}: {[c.text for c in row.cells]}")
    return lines


def parse_python_docx(path: Path) -> str:
    """python-docx で段落・表・ヘッダー/フッターをテキスト化する。

    Args:
        path: 入力 docx のパス。

    Returns:
        解析結果テキスト。
    """
    doc = Document(str(path))
    lines = []
    for block in _iter_block_items(doc):
        if isinstance(block, Paragraph):
            lines.append(_describe_paragraph(block))
            lines.extend(_drawing_lines(block))
        else:
            lines.extend(_describe_table(block))
    # コメントは comments パート内。本文からは参照 ID でのみ結び付く。
    for c in doc.comments:
        lines.append(f"[COMMENT #{c.comment_id} by {c.author}] {c.text!r}")
    # ヘッダー/フッターはセクション単位。markitdown(mammoth)は出力しないため差が出る。
    for i, sec in enumerate(doc.sections, start=1):
        for label, part in (("header", sec.header), ("footer", sec.footer)):
            text = "\n".join(p.text for p in part.paragraphs if p.text)
            if text:
                lines.append(f"[section {i} {label}] {text!r}")
    return "\n".join(lines)


def parse_markitdown(path: Path) -> str:
    """markitdown で Markdown に変換する。

    Args:
        path: 入力 docx のパス。

    Returns:
        Markdown テキスト。
    """
    return MarkItDown().convert(str(path)).text_content


def main() -> None:
    parser = argparse.ArgumentParser(description="python-docx と markitdown の比較")
    parser.add_argument("docx", type=Path, help="入力 docx")
    parser.add_argument("--out-dir", type=Path, default=Path("output"), help="出力先")
    args = parser.parse_args()

    args.out_dir.mkdir(parents=True, exist_ok=True)
    results = {
        "python-docx": (parse_python_docx(args.docx), "txt"),
        "markitdown": (parse_markitdown(args.docx), "md"),
    }
    # 手法ごとに 1 ファイル(<out-dir>/<docx名>.<手法>.<拡張子>)に保存する。
    for name, (content, ext) in results.items():
        out = args.out_dir / f"{args.docx.stem}.{name}.{ext}"
        out.write_text(content + "\n", encoding="utf-8")
        print(f"===== {name} -> {out} =====")
        print(content)


if __name__ == "__main__":
    main()

検証に使った sample.docx は7ページ構成で、ページごとに要素を1種類ずつ入れています。
python-docxでは作れない要素(テキストボックス・オートシェイプ・グラフ・SmartArt)が含まれるため、サンプルはMicrosoft WordをCOMで操作して作成しました。

ページ 内容
1 テキストボックス
2 テキストボックスとコメント
3 表
4 オートシェイプ
5 グラフ
6 SmartArt(項目A〜C)
7 画像

検証に使ったWordは次のリンクから確認できます。

比較結果

実際の出力は次のとおりです。

markitdownの出力

# 1. テキストボックス

これはテキストボックスです

# 2. テキストボックスとコメント

コメント対象の本文

コメント付きのテキストボックス

# 3. 表

|  |  |  |
| --- | --- | --- |
| R1C1 | R1C2 | R1C3 |
| R2C1 | R2C2 | R2C3 |
| R3C1 | R3C2 | R3C3 |

# 4. オートシェイプ

矢印

# 5. グラフ

# 6. SmartArt

# 7. 画像

![](data:image/jpeg;base64...)

python-docxの出力

- [P:Heading 1] '1. テキストボックス'
- [P:Normal] '' <image>
    [TEXTBOX/SHAPE] 'これはテキストボックスです'
- [P:Normal] ''
- [P:Heading 1] '2. テキストボックスとコメント'
- [P:Normal] 'コメント対象の本文' <image>
    [TEXTBOX/SHAPE] 'コメント付きのテキストボックス'
- [P:Normal] ''
- [P:Heading 1] '3. 表'
- [TABLE] 3x3
    row0: ['R1C1', 'R1C2', 'R1C3']
    row1: ['R2C1', 'R2C2', 'R2C3']
    row2: ['R3C1', 'R3C2', 'R3C3']
- [P:Normal] ''
- [P:Normal] ''
- [P:Heading 1] '4. オートシェイプ'
- [P:Normal] '' <image>
    [TEXTBOX/SHAPE] '矢印'
- [P:Normal] ''
- [P:Heading 1] '5. グラフ'
- [P:Normal] '' <image>
    [CHART barChart] categories: ['A', 'B', 'C']
      series '系列1': [10.0, 20.0, 30.0]
- [P:Normal] ''
- [P:Heading 1] '6. SmartArt'
- [P:Normal] '' <image>
    [SMARTART] ['項目A', '項目B', '項目C']
- [P:Normal] ''
- [P:Heading 1] '7. 画像'
- [P:Normal] '' <image>
[COMMENT #0 by Kitamura Taichi-北村 太一] 'これはコメントです'

比較まとめ

各ページのテキスト情報が取得できるかどうかを検証しました。

ページ 内容 markitdown python-docx
1 テキストボックス テキストが取得可能 XMLを読めば取得可能
2 テキストボックスとコメント 本文とテキストボックスは取得可能。コメントは取得不可 コメントも取得可能
3 表 Markdownの表形式で取得可能 セルごとに取れる
4 オートシェイプ テキストが取れる XMLを読めば取得可能
5 グラフ 取得不可 XMLを読めばカテゴリと系列の値が取得可能
6 SmartArt 取得不可 XMLを読めば各項目のテキストが取得可能
7 画像 画像内の文字は取得不可能 画像内の文字は取得不可能。※画像をファイル保存して別のOCRツールで解析することは可能

手軽だったmarkitdown(ページ1・3・4)

テキストボックス、オートシェイプ、表は、markitdownだと何も書かなくてもMarkdownになります。

# 3. 表

|  |  |  |
| --- | --- | --- |
| R1C1 | R1C2 | R1C3 |
| R2C1 | R2C2 | R2C3 |
| R3C1 | R3C2 | R3C3 |

python-docxは、本文の段落と表の取得APIはありますが、テキストボックスとオートシェイプのAPIはありません。
スクリプトのとおり、wps:txbx というXMLを直接読むコードを書く必要があります。

- [P:Normal] '' <image>
    [TEXTBOX/SHAPE] 'これはテキストボックスです'

なお、python-docxの <image> は、段落に図形(w:drawing)が含まれていることを示す目印です。テキストボックスやグラフも図形として扱われるため、本物の画像とは限りません。

表は、python-docxでも取れますが行ごとのリストとして取り出すだけです。

row0: ['R1C1', 'R1C2', 'R1C3']
row1: ['R2C1', 'R2C2', 'R2C3']
row2: ['R3C1', 'R3C2', 'R3C3']

Markdown形式にしたい場合は、自前で変換する必要があります。
また、markitdownの表は先頭に空のヘッダー行(| | | |)が付きます。これはWordの表にヘッダーという概念がないためです。

コメント(ページ2)

markitdownは本文とテキストボックスは出力しますが、コメントは出力しません。
python-docxは1.2.0から doc.comments でコメントを読めるようになり、作成者とテキストが取得できます。

[COMMENT #0 by Kitamura Taichi-北村 太一] 'これはコメントです'

ただし、コメントがどの文章に付いているかは、本文のXML(コメントID)をたどる必要があります。
レビュー指摘が入ったWordを読ませたい場合は、python-docxが必要です。

グラフとSmartArt(ページ5・6)

markitdownは、グラフもSmartArtも何も出力しません。見出しだけが残ります。

# 5. グラフ

# 6. SmartArt

python-docxにも、どちらを読むAPIもありません。ただし、データはdocx内の別パーツ(グラフは charts/chart*.xml、SmartArtは diagrams/data*.xml)に格納されているため、このXMLを直接読むコードを書けば取得できます。

    [CHART barChart] categories: ['A', 'B', 'C']
      series '系列1': [10.0, 20.0, 30.0]
    [SMARTART] ['項目A', '項目B', '項目C']

PowerPoint解析ではmarkitdownがグラフを表にしてくれましたが、Wordでは取れない点に注意が必要です。

画像(ページ7)

markitdownは画像を ![](data:image/jpeg;base64...) というMarkdownで出します。
画像データは省略されていて、画像の中身(絵や文字)が分かるわけではありません。

python-docxでも画像内の文字は取得できないですが、コードを書けば画像をバイナリファイルとして取得できるので、OCRツールと組み合わせれば、画像内の文字列を取得することができます。

まとめ

  • 本文・見出し・表・テキストボックスのテキスト化だけならmarkitdown。コード不要でそのままMarkdownになる
  • コメント、グラフ、SmartArtが必要ならpython-docx。コードは必要だが、markitdownが拾えないものも取得できる(グラフとSmartArtはXML解析が必要)

なお、今回の検証は1つのサンプルファイルによるもので、バージョンによって出力は変わる可能性があります。
実際の資料で試して確認してください。