Excel Structured Extraction Engine
[](https://pypi.org/project/exstruct/) [](https://pepy.tech/projects/exstruct)  [](https://github.com/harumiWeb/exstruct/actions/workflows/pytest.yml) [](https://app.codacy.com/gh/harumiWeb/exstruct/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [](https://codecov.io/gh/harumiWeb/exstruct) [](https://deepwiki.com/harumiWeb/exstruct)  [](https://github.com/sponsors/harumiWeb)
English
|
日本語
# ExStruct — Excel Structured Extraction Engine
ExStruct reads Excel workbooks into structured data and applies patch-based
editing workflows through a shared core. It provides extraction APIs, a
JSON-first editing CLI, and an MCP server for host-managed integrations, with
options tuned for LLM/RAG preprocessing, reviewable edit flows, and local
automation.
- In COM/Excel environments (Windows), it performs rich extraction.
- In non-COM environments (Linux/macOS):
- direct OOXML parsing extracts cells, shapes, charts, table candidates, and print areas on a best-effort basis
- if the LibreOffice runtime is available, cells, table candidates, shapes, and charts are also extracted on a best-effort basis
Detection heuristics, editing workflows, and output modes are adjustable for
LLM/RAG pipelines and local automation.
## Main Features
- **Excel -> structured JSON**: outputs cells, shapes, charts, SmartArt, table candidates, merged-cell ranges, print areas, and auto page-break areas by sheet or by area.
- **Output modes**:
- `light`: cells + table candidates + print areas + best-effort shapes/charts via direct OOXML for `.xlsx` / `.xlsm`
- `libreoffice`: best-effort non-COM mode for `.xlsx/.xlsm`. When the LibreOffice runtime is available, it adds merged cells, shapes, connectors, and charts
- `standard`: Excel COM mode with texted shapes + arrows, charts, SmartArt, and merged-cell ranges
- `verbose`: outputs all shapes with width/height and also emits cell hyperlinks
- **Formula extraction**: emits `formulas_map` (formula string -> cell coordinates) via OOXML or the selected openpyxl/COM path. It is enabled by default in `verbose` and can be controlled with `include_formulas_map`.
- **Formats**: JSON (compact by default, `--pretty` for formatting), YAML, and TOON (optional dependencies).
- **Workbook editing interfaces**: use the editing CLI for primary ExStruct edit flows, keep MCP for host-owned safety controls, and use `exstruct.edit` only when you need the same patch contract from Python.
- **Table detection tuning**: heuristics can be adjusted dynamically through the API.
- **Hyperlink extraction**: in `verbose` mode, or with `include_cell_links=True`, cell links are emitted in `links`.
- **Safe fallback**: `light` uses direct OOXML for `.xlsx` / `.xlsm` without Excel COM or LibreOffice. Unsupported OOXML or `colors_map` requests restart the complete openpyxl compatibility pipeline with an `ooxml_compatibility` warning; partial results are discarded. A drawing failure isolated to one sheet remains best-effort.
## Installation
```bash
pip install exstruct
```
Optional extras:
- Border-clustering acceleration: `pip install exstruct[fast]` (SciPy). Normal direct light extraction uses Python clustering. SciPy acceleration and `EXSTRUCT_BORDER_CLUSTER_BACKEND` selection apply to other modes and compatibility extraction; NumPy remains a core dependency.
- YAML: `pip install pyyaml`
- TOON: `pip install python-toon`
- Rendering (PDF/PNG): Excel + `pip install pypdfium2 pillow` (`mode=libreoffice` is not supported)
- Install these extras at once: `pip install exstruct[yaml,toon,render,fast]`
Platform note:
- On Debian/Ubuntu/WSL, install LibreOffice together with `python3-uno`. ExStruct probes a compatible system Python automatically for `mode=libreoffice`; if your environment needs an explicit interpreter, set `EXSTRUCT_LIBREOFFICE_PYTHON_PATH=/usr/bin/python3`.
- LibreOffice Python detection now runs the bundled bridge in `--probe` mode before selection. An incompatible `EXSTRUCT_LIBREOFFICE_PYTHON_PATH` fails fast instead of surfacing a delayed bridge `SyntaxError` during extraction.
- If the isolated temporary LibreOffice profile fails before the UNO socket becomes ready, ExStruct retries once with the shared/default LibreOffice profile as a compatibility fallback and reports per-attempt startup detail if both launches fail.
## Quick Start CLI
```bash
exstruct input.xlsx > output.json # compact JSON to stdout by default
exstruct input.xlsx -o out.json --pretty # write pretty JSON to a file
exstruct input.xlsx --format yaml # YAML (requires pyyaml)
exstruct input.xlsx --format toon # TOON (requires python-toon)
exstruct input.xlsx --sheets-dir sheets/ # write one file per sheet
exstruct input.xlsx --auto-page-breaks-dir auto_areas/ # always shown; execution requires standard/verbose + Excel COM
exstruct input.xlsx --alpha-col # output column keys as A, B, ..., AA
exstruct input.xlsx --include-backend-metadata # include shape/chart backend metadata
exstruct input.xlsx --mode light # cells + table candidates + best-effort OOXML shapes/charts
exstruct input.xlsx --mode libreoffice # best-effort extraction of shapes/connectors/charts without COM
exstruct input.xlsx --pdf --image # PDF and PNGs (Excel COM required)
```
Auto page-break export is available from both the API and the CLI when Excel/COM is available. The CLI always exposes `--auto-page-breaks-dir`, but validates it at execution time.
`mode=libreoffice` rejects `--pdf`, `--image`, and `--auto-page-breaks-dir` early, and `mode=light` also rejects `--auto-page-breaks-dir`. Use `standard` or `verbose` with Excel COM for those features.
By default, the CLI keeps legacy 0-based numeric string column keys (`"0"`, `"1"`, ...). Use `--alpha-col` when you need Excel-style keys (`"A"`, `"B"`, ...).
By default, serialized shape/chart output omits backend metadata (`provenance`, `approximation_level`, `confidence`) to reduce token usage. Use `--include-backend-metadata` or the corresponding Python/MCP option when you need it.
## Quick Start Editing CLI
```bash
exstruct patch --input book.xlsx --ops ops.json --backend openpyxl
exstruct patch --input book.xlsx --ops - --dry-run --pretty < ops.json
exstruct make --output new.xlsx --ops ops.json --backend openpyxl
exstruct ops list
exstruct ops describe create_chart --pretty
exstruct validate --input book.xlsx --pretty
```
- `patch` and `make` print JSON `PatchResult` to stdout.
- `ops list` / `ops describe` expose the public patch-op schema.
- `validate` reports workbook readability (`is_readable`, `warnings`, `errors`).
Recommended edit flow:
1. Build patch ops.
2. Run `exstruct patch --dry-run` and inspect `PatchResult`, warnings, and diff.
3. Pin `--backend openpyxl` when you want the dry run and the real apply to use the same engine.
4. If you keep `--backend auto`, inspect `PatchResult.engine`; on Windows/Excel hosts the real apply may switch to COM.
5. Re-run without `--dry-run` only after the result is acceptable.
## ExStruct CLI Skill
ExStruct also ships one repo-owned Skill for agents that should follow the
editing CLI safely instead of rediscovering the workflow each time.
Canonical repo source:
- `.agents/skills/exstruct-cli/`
You can install it with the following single command:
```bash
npx skills add harumiWeb/exstruct/.agents/skills --skill exstruct-cli
```
If your runtime cannot use `npx skills add`, place the same folder manually
into a local skill directory that discovers `SKILL.md`-based skills.
Use this Skill when the agent needs help choosing between `patch`, `make`,
`validate`, `ops list`, and `ops describe`, or when it should follow the safe
`validate -> dry-run -> inspect -> apply -> verify` workflow.
Example prompt for agents:
> Use `$exstruct-cli` to choose the right ExStruct editing CLI command, follow a safe validate/dry-run/inspect workflow, and explain any backend constraints for this workbook task.
## MCP Server (stdio)
MCP is the integration / compatibility layer around the same editing core. Use
it when you need host-managed path restrictions, transport mapping, artifact
mirroring, or approval-aware agent execution. For ordinary Python workbook
editing, `openpyxl` / `xlwings` are usually a better fit. For local shell or
agent workflows, prefer the editing CLI.
### Quick Start with `uvx` (recommended)
You can run it directly without installation:
```bash
uvx --from 'exstruct[mcp]' exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict rename
```
Benefits:
- no `pip install` required
- automatic dependency management
- isolated environment
- easy version pinning: `uvx --from 'exstruct[mcp]==0.4.4' exstruct-mcp`
### Traditional installation
You can also install it with pip:
```bash
pip install exstruct[mcp]
exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict rename
```
Available tools:
| Tool name | Description |
| ------------------------------- | -------------------------------------- |
| `exstruct_extract` | Extracts data from a workbook. |
| `exstruct_capture_sheet_images` | Captures sheet images. |
| `exstruct_make` | Creates a new workbook. |
| `exstruct_patch` | Applies editing patches to a workbook. |
| `exstruct_read_json_chunk` | Reads extracted JSON chunks. |
| `exstruct_read_range` | Reads cells from a specified range. |
| `exstruct_read_cells` | Reads data cell by cell. |
| `exstruct_read_formulas` | Reads cell formulas. |
| `exstruct_validate_input` | Validates input data. |
For more details and API usage, see the documentation site:
[MCP Server](https://harumiweb.github.io/exstruct/mcp/)
## Quick Start Python Extraction
```python
from pathlib import Path
from exstruct import extract, export, set_table_detection_params
# Tune table detection (optional)
set_table_detection_params(table_score_threshold=0.3, density_min=0.04)
# Modes: "light" / "standard" / "verbose"
wb = extract("input.xlsx", mode="standard") # standard does not emit links by default
export(wb, Path("out.json"), pretty=False) # compact JSON
export(wb, Path("out.json"), include_backend_metadata=True) # opt into backend metadata
# Helpful model methods: iteration, indexing, and direct serialization
first_sheet = wb["Sheet1"] # get a sheet with __getitem__
for name, sheet in wb: # __iter__ yields (name, SheetData)
print(name, len(sheet.rows))
wb.save("out.json", pretty=True) # save WorkbookData based on extension
first_sheet.save("sheet.json") # save SheetData the same way
print(first_sheet.to_yaml()) # YAML string (requires pyyaml)
print(first_sheet.to_json(include_backend_metadata=True)) # opt in when needed
# ExStructEngine: per-instance configuration
from exstruct import (
DestinationOptions,
ExStructEngine,
FilterOptions,
FormatOptions,
OutputOptions,
StructOptions,
export_auto_page_breaks,
)
engine = ExStructEngine(
options=StructOptions(mode="verbose"), # verbose includes hyperlinks by default
output=OutputOptions(
format=FormatOptions(pretty=True),
filters=FilterOptions(
include_shapes=False,
include_backend_metadata=True,
), # opt into backend metadata when needed
destinations=DestinationOptions(sheets_dir=Path("out_sheets")), # save per-sheet files
),
)
wb2 = engine.extract("input.xlsx")
engine.export(wb2, Path("out_filtered.json"))
# Enable hyperlinks in standard mode
engine_links = ExStructEngine(options=StructOptions(mode="standard", include_cell_links=True))
with_links = engine_links.extract("input.xlsx")
# Export one file per print area
from exstruct import export_print_areas_as
export_print_areas_as(wb, "areas", fmt="json", pretty=True)
# Extract / export auto page-break areas (COM only; raises if no auto breaks exist)
engine_auto = ExStructEngine(
output=OutputOptions(
destinations=DestinationOptions(auto_page_breaks_dir=Path("auto_areas"))
)
)
wb_auto = engine_auto.extract("input.xlsx") # includes SheetData.auto_print_areas
engine_auto.export(wb_auto, Path("out_with_auto.json"))
export_auto_page_breaks(wb_auto, "auto_areas", fmt="json", pretty=True)
```
**Note (non-COM environments):** even when Excel COM is unavailable, cells + `table_candidates` are still returned, and `.xlsx` / `.xlsm` keep best-effort OOXML `shapes` / `charts` when available.
## Table Detection Parameters
```python
from exstruct import set_table_detection_params
set_table_detection_params(
table_score_threshold=0.35, # raise it to be stricter
density_min=0.05,
coverage_min=0.2,
min_nonempty_cells=3,
)
```
Higher values reduce false positives. Lower values reduce missed detections.
## Output Modes
- **light**: direct OOXML cells + table candidates + print areas and best-effort shapes/connectors/charts for `.xlsx` / `.xlsm`. The normal path does not import openpyxl, pandas, SciPy, or xlwings.
- **standard**: texted shapes + arrows, charts (when COM is available), and table candidates. Cell hyperlinks are emitted only when `include_cell_links=True`.
- **verbose**: all shapes, charts, `table_candidates`, hyperlinks, and `colors_map`.
## Error Handling / Fallback
- If Excel COM is unavailable, extraction falls back to cells + table candidates automatically; `.xlsx` / `.xlsm` still preserve best-effort OOXML shapes/charts when available.
- A per-sheet drawing failure omits that sheet's affected drawing artifacts while preserving healthy sheets. An unsupported OOXML construct or failure in any other direct pipeline stage discards all partial OOXML data, restarts the complete openpyxl compatibility pipeline, and logs `ooxml_compatibility`.
- The CLI writes errors to stdout/stderr and exits with a non-zero status on failure.
## Optional Rendering
Excel and `pypdfium2` are required:
```bash
exstruct input.xlsx --pdf --image --dpi 144
```
This writes `