Xlsx

Excel の .xlsx ブックと CSV を作り、読み、直します。

skill の情報

参考: SKILL.md 全文

Xlsx Skill

Python と openpyxl を使って Excel の .xlsx ブックを扱います。数式や グラフを含む、体裁の整った複数シートのブックを作り、既存のファイルの 中身を調べたり書き出したりし、セルや構造を直し、CSV との相互変換を します。補助スクリプトはすべて argparse のコマンドで、JSON を表示し、 入出力は UTF-8 をはっきり指定して行います。

こんなときに使います

• .xlsx の報告書を作るとき: 複数シート、数値の書式、体裁、

セルの結合、ウィンドウ枠の固定、フィルター、条件付き書式、 グラフ、入力規則のドロップダウン、Excel 本来のテーブル、 名前の定義、リンク、セルのメモ、シートの保護。

• ブックを読むとき: シートの一覧、データを JSON や CSV として

書き出すこと、数式と計算済みの値の一覧、メモ、名前の定義、テーブル。

• 既存のファイルを直すとき: セルの設定、行の追加、行や列の

挿入と削除（xlsx_restructure.py を使えば参照も追従します）、 シートの複製と名前の変更、テーブル、名前、メモ、保護。

• LibreOffice を使い、画面なしで数式を計算し直すとき

（xlsx_recalc.py）。

• 型の推測や UTF-8 以外の文字コードを含む、CSV とのやり取り。
• 古い .xls のバイナリー形式には使いません（先に LibreOffice で

変換してください: soffice --headless --convert-to xlsx old.xls）。

事前に必要なもの

• Python 3.10 以上と openpyxl（pip install openpyxl）。ほかに

外部のパッケージは要りません。あとはすべて標準ライブラリーです。

• 任意: 画面なしでの再計算や形式の変換のための LibreOffice

（soffice）。

実行のしかた

補助スクリプトは、この skill の scripts/ ディレクトリーから terminal ツールで実行します（どのスクリプトも --help に対応します）:

python scripts/xlsx_create.py spec.json report.xlsx   # build from JSON spec
python scripts/xlsx_read.py report.xlsx --sheets      # inventory
python scripts/xlsx_read.py report.xlsx --json --sheet Data
python scripts/xlsx_read.py report.xlsx --formulas
python scripts/xlsx_edit.py report.xlsx --sheet Data --set B2=42 --recalc
python scripts/xlsx_restructure.py report.xlsx --sheet Data --insert-rows 3:2
python scripts/xlsx_recalc.py report.xlsx
python scripts/csv_to_xlsx.py data.csv out.xlsx --encoding utf-8
python scripts/xlsx_to_csv.py report.xlsx out.csv --sheet Data

JSON の指定は write_file で書き、スクリプトが出す JSON は read_file か標準出力からそのまま確かめてください。

早見表

手順

1. 作ります: JSON の指定を書きます（形式は

xlsx_create.py --help とその説明文に書いてあります）。シートごとに rows（数や文字、または体裁を付けたセルの指定）、抜き差しで 上書きする cells、column_widths、row_heights、merges、 freeze_panes、autofilter、conditional_formats（cell_is の 条件とカラースケール）、charts（セル範囲からの棒・折れ線・円）、 validations（ドロップダウン）、tables（スタイル名を付けた Excel 本来のテーブル）、protection を指定できます。ブック全体の defined_names は、名前と参照先の対応を表します。セルの指定には hyperlink と note も書けます。型のある値は、JSON の数値と 真偽値がそのまま通り、日付は {"value": "2026-01-31", "type": "date"} の形にします。 数値の書式は Excel の書式文字列です。通貨は "$#,##0.00"、 百分率は "0.0%"、日付は "yyyy-mm-dd" のように書きます。

1. 数式: 指定の中で "formula": "SUM(B2:B9)"、または編集時に

--set "C1==SUM(A:A)" で設定します。数式を書くときは、指定に "full_calc_on_load": true を足すか、編集時に --recalc を 付けてください。これでブックの fullCalcOnLoad フラグが立ち、 Excel や LibreOffice が開いたときにすべて計算し直します。 openpyxl 自体は数式を決して計算しません。

1. 読みます: 一覧（名前、大きさ、結合された範囲、グラフの数、

テーブル、保護、名前の定義）は --sheets、データは --json/--csv、数式の文字列と計算済みの結果を並べて見るには --formulas、セルのコメントは --notes、名前の定義は --names を使います。計算済みの結果は、そのファイルを最後に 本物の表計算ソフトが保存したときだけ入っています。openpyxl で 作ったばかりのファイルでは null が返ります。画面なしで結果を 出したいときは xlsx_recalc.py file.xlsx を実行し（LibreOffice を 使います。soffice が無いときは {"recalculated": false, ...} を 表示して 0 で終了します）、そのあと --data-only で読み直して ください。

1. 直します: xlsx_edit.py は、名前の変更と複製を先に行い、次に

行や列の構造の変更、最後に --set/--append を行います。--out を 指定しない限りその場で書き換えるので、元のファイルが必要なら 先にコピーしてください。

1. 構造を組み替えます: 数式・結合・テーブル・フィルターのある

シートで行や列を挿入・削除するときは、xlsx_edit.py ではなく xlsx_restructure.py を使ってください。すべてのシートの数式の 参照（$ 付きの絶対参照、範囲、他シートへの参照）を書き換え、 結合・フィルター・ウィンドウ枠の固定・入力規則と条件付き書式の 範囲・テーブルの参照・名前の定義・行と列の寸法をずらしたうえで、 not_shifted の一覧を含む JSON の報告を表示します。決まりごとと 限界は references/restructuring.md にあります。

1. CSV とのやり取り: csv_to_xlsx.py はセルごとに整数・小数・

真偽値・ISO 形式の日付を推測し、見出しの行に体裁を付けます。 xlsx_to_csv.py は ISO 形式の日付を書き、空のセルは空文字にします。 どちらも既定は UTF-8 で、--encoding を受け付けます（Excel と 相性のよい BOM 付きなら utf-8-sig、古い Windows の書き出しなら cp1252 など）。

PDF に変換する

LibreOffice は画面なしで変換できます（シート 1 枚を CSV で書き出す のにも使えます）:

soffice --headless --convert-to pdf report.xlsx --outdir out/
soffice --headless --convert-to csv report.xlsx --outdir out/  # 1st sheet only

CSV に入るのは最初のシートだけです。ほかのシートは xlsx_to_csv.py --sheet NAME を使ってください。soffice が無い ときは、LibreOffice を入れるか、変換しないままファイルを渡します。

つまずきやすいところ

• openpyxl は計算しません。 数式の結果を取れるのは

load_workbook(path, data_only=True) を使ったときだけで、しかも そのファイルを以前に Excel か LibreOffice が保存していた場合に 限られます。そうでなければ None が返ります。

• xlsx_edit.py の挿入と削除では参照がずれません（openpyxl

そのままの動きです）。参照を追従させるには xlsx_restructure.py を使ってください。ただしそれでも、グラフの位置、画像、条件付き 書式の条件そのものの数式は動かせません。JSON の報告にある not_shifted の一覧と references/restructuring.md を読んでください。

• シートの保護は安全対策ではありません。 --protect は xlsx の

標準的なシート保護のハッシュを設定するだけで、行儀のよいアプリに 「ここは編集しないで」と伝える以上のことはしません。zip の中の XML を 直したり、LibreOffice でチェックを外したりすれば誰でも解除できます。 秘密や改ざん防止を、これに頼ってはいけません。暗号化は一切しません。

• data_only=True で読んでから保存すると、数式がすべて何も

言わずに消えます（計算済みの値に置き換わります）。それが目的で ない限り、そうやって読んだブックを保存してはいけません。

• 読み込むとグラフや画像が落ちます: openpyxl はグラフを

そのまま往復させられないので、グラフのあるブックを直して保存すると グラフが消えます。直したあとにグラフを付け直すか、グラフのある ファイルを保存し直さないようにしてください。

• CSV の地域差の罠: 文字コードは必ずはっきり渡してください

（スクリプトはすでにそうしています）。ヨーロッパの CSV は区切りに ; を使い、小数点にコンマを使うことがよくあります。 --delimiter ';' を使い、"12,5" のような値は文字列のままに なると思っておいてください。

• 日付は日時になります: Excel は日付を連番で保存し、openpyxl は

datetime/date のオブジェクトを返します。ここでの書き出しは ISO 形式の文字列にします。

• シート名は 31 文字までで、[ ] : * ? / \ は使えません。

確認

• 作ったあと: xlsx_read.py out.xlsx --sheets を実行し、シート名・

大きさ・結合された範囲・グラフの数が意図どおりか確かめます。

• --json でデータを書き出し、元の値と比べます。
• 直したあと: 触った範囲をもう一度書き出します。数式を書いたなら、

--formulas に並ぶことと --recalc を付けたことを確かめます。

• xlsx_restructure.py のあと: JSON の報告を読み、--formulas と

--sheets をもう一度実行して、参照と範囲が思ったところに収まって いるか確かめます。

• 見た目までしっかり確かめたいときは LibreOffice で開きます:

soffice --headless --convert-to pdf out.xlsx を実行し、その PDF を 見てください。