Python-docx ライブラリ完全ガイド：Word文書操作をマスターしよう 📄✨

python-docxは、Word 2007以降で採用されているOffice Open XML（OOXML）形式（.docx）のファイルを操作するためのPythonライブラリです。Wordアプリケーション本体を操作するわけではなく、ファイル形式の仕様に基づいて直接ファイルを生成・編集します。

主な機能としては、以下のようなものがあります。

• 新規Word文書の作成: 空の文書を作成し、コンテンツを追加できます。
• 既存Word文書の読み込みと編集: 既存の.docxファイルを開き、内容を読み取ったり、変更を加えたりできます。
• テキストの追加と書式設定: 段落や見出しを追加し、太字、斜体、下線、フォントサイズ、色などの書式を設定できます。
• 表（テーブル）の挿入と編集: 新しい表を作成したり、既存の表にアクセスしてセル内容を編集したりできます。
• 画像の挿入: 文書内に画像を挿入できます。（この記事では画像タグは扱いませんが、機能としては存在します。）
• スタイルの利用: Wordに組み込まれているスタイル（見出し1, 標準など）を適用したり、独自のスタイルを定義したりできます。
• セクション、ヘッダー/フッターの操作: 文書のセクションを管理し、ヘッダーやフッターに内容を追加できます。

これらの機能により、定型報告書の自動生成、データベースからのデータに基づいた請求書の作成、複数の文書の一括編集など、様々な業務を自動化・効率化することが可能になります。 Windowsだけでなく、macOSやLinuxなど、Pythonが動作する環境であれば利用できる点も大きなメリットです。

python-docxのインストールは非常に簡単です。Pythonのパッケージ管理ツールであるpipを使います。ターミナル（コマンドプロンプトやPowerShellなど）を開き、以下のコマンドを実行してください。

pip install python-docx

通常、これだけでインストールは完了します。依存関係のあるライブラリ（例えばlxml）も自動的にインストールされます。

インストールが成功したか確認するには、Pythonのインタラクティブシェルやスクリプトでライブラリをインポートしてみます。

import docx

print("python-docxのインポートに成功しました！🎉")

上記コードを実行してエラーが出なければ、インストールは正常に完了しています。もしModuleNotFoundErrorのようなエラーが出る場合は、pipコマンドが正しく実行されたか、Python環境が適切に設定されているかを確認してください。

まずは、python-docxを使って新しいWord文書を作成し、基本的な要素を追加してみましょう。

1. 新規文書オブジェクトの作成

最初に、docxモジュールからDocumentクラスをインポートし、そのインスタンスを作成します。これがWord文書全体を表すオブジェクトになります。

from docx import Document

# 新しいDocumentオブジェクトを作成
doc = Document()

2. 段落の追加

文書にテキストを追加する最も基本的な方法は、段落を追加することです。Documentオブジェクトのadd_paragraph()メソッドを使用します。

# 段落を追加し、テキストを設定
paragraph1 = doc.add_paragraph("これは最初の段落です。")
paragraph2 = doc.add_paragraph("これは二番目の段落です。😊")

# 既存の段落にテキストを追加することも可能
paragraph1.add_run(" ここにテキストを追加します。")

add_paragraph()は新しい段落オブジェクト（Paragraphオブジェクト）を返します。add_run()メソッドを使うと、既存の段落に続けてテキストを追加できます。Runオブジェクトは、同じ書式を持つテキストの連続した塊を表します。

3. 見出しの追加

見出しを追加するにはadd_heading()メソッドを使います。第一引数に見出しのテキスト、第二引数（オプション）に見出しレベルを指定します。レベル0はタイトル用、レベル1〜9が標準的な見出しレベルに対応します。

# ドキュメントのタイトル（レベル0）
doc.add_heading('これは文書タイトルです', level=0)

# レベル1の見出し
doc.add_heading('第1章 はじめに', level=1)

# レベル2の見出し
doc.add_heading('1.1 背景', level=2)

4. テキストの書式設定（太字、斜体）

特定のテキスト部分の書式を変更するには、add_run()でRunオブジェクトを取得し、そのプロパティを設定します。

# 新しい段落を追加
p = doc.add_paragraph('通常のテキスト、')

# 太字のテキストを追加
run_bold = p.add_run('これは太字')
run_bold.bold = True

# 通常テキストを追加
p.add_run('、そして')

# 斜体のテキストを追加
run_italic = p.add_run('これは斜体です。')
run_italic.italic = True

# 太字かつ斜体のテキスト
run_bold_italic = p.add_run(' 太字で斜体。')
run_bold_italic.bold = True
run_bold_italic.italic = True

Runオブジェクトには他にもunderline（下線）、font.size（フォントサイズ）、font.name（フォント名）、font.color.rgb（文字色）などのプロパティがあります。

from docx.shared import Pt, RGBColor
from docx.enum.text import WD_COLOR_INDEX # WD_COLOR_INDEXは古い形式の色指定に使うこともあります

# ... (Documentオブジェクト作成など)

p_font = doc.add_paragraph('フォントサイズと色を変更します。')
run_font = p_font.runs[0] # 最初のRunオブジェクトを取得

# フォントサイズを14ポイントに設定
run_font.font.size = Pt(14)

# フォント名を「ＭＳ ゴシック」に設定
run_font.font.name = 'ＭＳ ゴシック'
# ASCII文字用フォントも指定しておくと良い場合がある
run_font.font._element.rPr.rFonts.set(qn('w:eastAsia'), 'ＭＳ ゴシック')

# 文字色を赤色に設定 (RGBで指定)
run_font.font.color.rgb = RGBColor(0xFF, 0x00, 0x00) # RGB(255, 0, 0)

5. 改ページの追加

文書の途中で改ページを挿入したい場合は、add_page_break()メソッドを使用します。

# 最初のページの内容
doc.add_paragraph("これは1ページ目の内容です。")

# 改ページを挿入
doc.add_page_break()

# 次のページの内容
doc.add_paragraph("これは2ページ目の内容です。")

6. 文書の保存

最後に、作成したDocumentオブジェクトを.docxファイルとして保存します。save()メソッドを使用し、引数にファイル名を指定します。

# 文書をファイルに保存
file_path = 'my_first_document.docx'
doc.save(file_path)

print(f"文書 '{file_path}' が正常に保存されました。💾")

これで、基本的な要素を含むWord文書が作成されました！指定したパスにファイルが生成されているはずです。

python-docxは、新規作成だけでなく、既存の.docxファイルを読み込んで内容を解析することも得意です。

1. 既存文書の読み込み

既存のファイルを読み込むには、Documentクラスのコンストラクタにファイルパスを渡します。

from docx import Document

# 既存のWordファイルを読み込む
try:
    doc_existing = Document('path/to/your/existing_document.docx')
    print("既存文書の読み込みに成功しました。")
except Exception as e:
    print(f"エラー: ファイルの読み込みに失敗しました - {e}")
    # ここで処理を中断するか、デフォルトのDocumentを作成するなどの対応が必要
    doc_existing = Document() # 例: エラー時は空のドキュメントを作成

ファイルが存在しない、または形式が不正な場合はエラーが発生する可能性があるため、try...exceptブロックで囲むのが安全です。

2. 段落テキストの取得

読み込んだ文書のすべての段落にアクセスするには、Documentオブジェクトのparagraphs属性を使用します。これはParagraphオブジェクトのリストです。各段落のテキストはtext属性で取得できます。

print("\n--- 文書内の全段落 ---")
for i, para in enumerate(doc_existing.paragraphs):
    print(f"段落 {i+1}: {para.text}")

特定の段落にアクセスしたい場合は、インデックスを指定します（例: doc_existing.paragraphs[0]）。

3. 表（テーブル）の内容取得

文書内の表にアクセスするには、Documentオブジェクトのtables属性を使用します。これはTableオブジェクトのリストです。

print("\n--- 文書内の全テーブル ---")
if not doc_existing.tables:
    print("この文書にはテーブルが含まれていません。")
else:
    for i, table in enumerate(doc_existing.tables):
        print(f"\nテーブル {i+1}: ({len(table.rows)}行 x {len(table.columns)}列)")
        # 各セルの内容を取得
        for row_idx, row in enumerate(table.rows):
            row_data = []
            for cell_idx, cell in enumerate(row.cells):
                row_data.append(f"({row_idx},{cell_idx}): '{cell.text.strip()}'") # strip()で前後の空白を除去
            print(f"  行 {row_idx + 1}: {', '.join(row_data)}")

Tableオブジェクトにはrows（行のリスト）やcolumns（列のリスト）属性があります。row.cellsで行内のセルのリスト（Cellオブジェクト）を取得し、cell.textでセル内のテキストを取得できます。

このように、既存の文書から情報を抽出して、データ分析や他のシステムへの連携に活用することができます。

基本的な操作に慣れたら、さらに高度な機能を使ってみましょう。ここでは、表の作成、スタイルの適用、既存文書への追記について解説します。

1. 表（テーブル）の作成

文書に表を追加するには、add_table()メソッドを使用します。行数と列数を指定して表を作成し、その後、セルにデータを入力していきます。

from docx import Document
from docx.shared import Inches, Pt
from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
from docx.enum.table import WD_TABLE_ALIGNMENT, WD_CELL_VERTICAL_ALIGNMENT

doc_table = Document()
doc_table.add_heading('製品リスト', level=1)

# データ準備
data = [
    ('商品ID', '商品名', '価格(円)'),
    (101, '高性能ノートPC', 150000),
    (102, 'ワイヤレスマウス', 3500),
    (103, 'メカニカルキーボード', 12000)
]

# 3行4列のテーブルを作成 (ヘッダー行 + データ3行)
num_rows = len(data)
num_cols = len(data[0]) if num_rows > 0 else 0

if num_rows > 0 and num_cols > 0:
    table = doc_table.add_table(rows=1, cols=num_cols) # まずヘッダー行のみ作成
    table.style = 'Table Grid' # 表のスタイルを適用 (組み込みスタイル)
    table.alignment = WD_TABLE_ALIGNMENT.CENTER # 表全体を中央揃え

    # テーブル幅の設定 (例: ページ幅に合わせる)
    # table.autofit = True # 内容に合わせて自動調整する場合
    # table.allow_autofit = False # 自動調整を無効にする場合
    # 個別に幅を指定することも可能 (後述)

    # ヘッダー行の設定
    hdr_cells = table.rows[0].cells
    for i, header_text in enumerate(data[0]):
        cell = hdr_cells[i]
        cell.text = str(header_text)
        # ヘッダーを太字にする
        cell.paragraphs[0].runs[0].font.bold = True
        # ヘッダーを中央揃え
        cell.paragraphs[0].alignment = WD_PARAGRAPH_ALIGNMENT.CENTER
        # ヘッダーセルの垂直方向中央揃え
        cell.vertical_alignment = WD_CELL_VERTICAL_ALIGNMENT.CENTER

    # データ行の追加と設定
    for item in data[1:]:
        row_cells = table.add_row().cells
        for i, cell_data in enumerate(item):
            cell = row_cells[i]
            cell.text = str(cell_data)
            # 価格列 (3列目) を右揃えにする
            if i == 2:
                cell.paragraphs[0].alignment = WD_PARAGRAPH_ALIGNMENT.RIGHT
            # 全データセルの垂直方向中央揃え
            cell.vertical_alignment = WD_CELL_VERTICAL_ALIGNMENT.CENTER

    # 列幅の設定 (オプション)
    # 例: 1列目を1インチ、2列目を3インチ、3列目を1.5インチに設定
    widths = (Inches(1.0), Inches(3.0), Inches(1.5))
    for i, width in enumerate(widths):
        if i < len(table.columns): # 列数が合っているか確認
             # table.columns[i].width = width # 直接 width 設定
             # または各セルの幅を設定 (より確実な場合がある)
             for cell in table.columns[i].cells:
                 cell.width = width

    doc_table.add_paragraph("\n上記の表はpython-docxで作成されました。")

    doc_table.save('document_with_table.docx')
    print("表を含む文書が保存されました。📊")
else:
    print("データが空のため、表は作成されませんでした。")

上記の例では、まずヘッダー行だけを持つ表を作成し、add_row()メソッドでデータ行を追加しています。セルの内容設定、文字揃え（alignment）、垂直方向の配置（vertical_alignment）、表全体のスタイルや配置も設定できます。列幅はInchesやCmを使って指定できます。

# セルの結合 (左上のセルを残して結合)
# 例: 最初の行の1列目と2列目を結合
cell_a = table.cell(0, 0) # 左上のセル
cell_b = table.cell(0, 1) # 右隣のセル
merged_cell = cell_a.merge(cell_b)
merged_cell.text = '結合されたセル'
merged_cell.paragraphs[0].alignment = WD_PARAGRAPH_ALIGNMENT.CENTER

# セルの分割 (現在はpython-docxの標準機能では直接サポートされていないようです)
# 分割したい場合は、表構造を作り直すなどの工夫が必要になることがあります。

2. スタイルの適用

Wordには「見出し1」「標準」「引用」など、多くの組み込みスタイルがあります。これらを適用することで、文書全体のデザイン統一や構造化が容易になります。add_paragraph()やadd_heading()時にstyle引数を指定するか、既存のParagraphオブジェクトのstyle属性にスタイル名（またはスタイルオブジェクト）を設定します。

from docx import Document
from docx.shared import Pt
# from docx.enum.style import WD_STYLE_TYPE # スタイルタイプ確認用
# from docx.styles.styles import Styles # スタイル一覧取得用 (高度)

doc_style = Document()

# スタイル名を指定して段落を追加
doc_style.add_paragraph('これは標準スタイルの段落です。') # デフォルトは 'Normal' or '標準'
doc_style.add_paragraph('これは引用スタイルのテキストです。', style='Intense Quote')
doc_style.add_paragraph('箇条書きリストの項目1', style='List Bullet')
doc_style.add_paragraph('箇条書きリストの項目2', style='List Bullet')
doc_style.add_paragraph('番号付きリストの項目1', style='List Number')
doc_style.add_paragraph('番号付きリストの項目2', style='List Number')

# 既存の段落にスタイルを適用
p_normal = doc_style.add_paragraph('この段落のスタイルを変更します。')
p_normal.style = doc_style.styles['Heading 2'] # '見出し 2' スタイルを適用

# 利用可能なスタイルを確認 (デバッグ用)
# print("\n--- 利用可能な段落スタイル ---")
# paragraph_styles = [s for s in doc_style.styles if s.type == WD_STYLE_TYPE.PARAGRAPH]
# for s in paragraph_styles:
#     print(f"Style Name: {s.name}")

doc_style.save('document_with_styles.docx')
print("スタイルを適用した文書が保存されました。🎨")

利用可能な組み込みスタイル名は、WordのUIで表示される名前（日本語環境では日本語）とは異なる場合があります。公式ドキュメントや、上記コード例のコメントアウト部分のようにして利用可能なスタイル名を確認するのが確実です。英語のスタイル名（例: ‘Heading 1’, ‘Body Text’, ‘List Paragraph’）で指定することが多いです。

3. 既存文書への追記

既存の文書を読み込み、その末尾に新しい内容を追加することも簡単です。

from docx import Document

existing_file = 'my_first_document.docx' # 最初に作成したファイル
output_file = 'my_first_document_appended.docx'

try:
    # 既存ファイルを読み込む
    doc_append = Document(existing_file)

    # 文書の末尾に新しい内容を追加
    doc_append.add_paragraph("\n--- ここから追記 ---") # 区切り線代わりの段落
    doc_append.add_heading("追記セクション", level=2)
    doc_append.add_paragraph("これは既存の文書に追加された新しい段落です。")
    doc_append.add_paragraph("追記は簡単ですね！👍")

    # 変更を新しいファイル名で保存（元のファイルを上書きしないように注意）
    doc_append.save(output_file)
    print(f"文書 '{existing_file}' に追記し、'{output_file}' として保存しました。")

except FileNotFoundError:
    print(f"エラー: ファイル '{existing_file}' が見つかりません。")
except Exception as e:
    print(f"エラー: 追記中に問題が発生しました - {e}")

重要なのは、save()メソッドで元のファイルとは違う名前を指定することです。これにより、誤って元の文書を上書きしてしまうのを防げます。

python-docxは様々な場面で活用できます。ここではいくつかの具体的な利用シーンを紹介します。

python-docxをより効果的に使うためのヒントや、陥りやすい注意点をいくつか紹介します。

この記事では、Pythonライブラリ「python-docx」を使ってWord文書を操作する方法について、インストールから基本的な使い方、応用的なテクニック、そして活用事例まで幅広く解説しました。

python-docxを使えば、これまで手作業で行っていた煩雑なWord文書作成・編集作業を自動化し、大幅な時間短縮とヒューマンエラーの削減が期待できます。特に定型的な文書作成や大量の文書処理において、その威力は絶大です。

今回紹介した機能はpython-docxの一部に過ぎません。公式ドキュメントなどを参考に、ぜひ様々な機能を試してみてください。あなたの業務効率化に、python-docxが貢献できれば幸いです。😊

さあ、PythonでWord文書操作の世界に飛び込みましょう！ Happy Coding! 💻✨