grepxcel

Stop writing custom Python for every Excel template. Define the layout once in a pattern spreadsheet, extract clean JSON from any file that follows it.

pip install grepxcel

Capabilities at a glance:

• Pattern file — describe any spreadsheet's layout once; reuse it across all matching files with no code changes
• Anchor-based — locates data by content, not position, so it keeps working when rows or columns shift between files
• LLM drafter — auto-generate a starter pattern from any file in ~30 seconds (grepxcel draft file.xlsx)
• Visual wizard — browser UI: click cells to classify, download the pattern (grepxcel web-wizard file.xlsx)
• CI-ready — deterministic, --strict exit-2 mode, JSON / CSV / colored-Excel output, Python 3.11–3.15
• Security-hardened — ReDoS guard, ZIP-bomb protection, CSRF hardening on the web wizard
• MCP server — expose grepxcel as a tool in Claude, Cursor, and any MCP-compatible AI agent (pip install 'grepxcel[mcp]')

The problem

You get Excel files from suppliers, clients, or other departments. Every template is different. You write Python to parse each one — and it silently breaks the moment someone moves a column or renames a header.

The solution

Describe the layout once in a pattern file. Run grepxcel extract. Get clean, structured JSON. When a file doesn't match the pattern, grepxcel flags exactly what went wrong — it is designed to fail loudly rather than produce silent errors, so automated pipelines can catch problems early.

pattern.xlsx  +  data.xlsx  →  { "po": { "number": "PO-2026" }, "line": [ {…} ] }

See it in action (2 minutes)

1. Generate example files:

grepxcel generate-examples
cd grepxcel-examples/01_simple_invoice

2. Look at what you have — a pattern file and a data file:

pattern.xlsx:  "Here is what the invoice looks like"
data.xlsx:     "Here is an actual invoice"

3. Extract:

grepxcel extract -p pattern.xlsx data.xlsx

4. Get clean JSON:

{
  "inv":    { "number": "AB123456", "date": "2026-03-15" },
  "client": { "name": "Alice Wonderland", "email": "alice@wonderland.example" },
  "amount": { "net": 120, "vat": 24, "gross": 144 }
}

That's it. The same pattern works on next month's invoice — as long as the layout stays consistent.

Who is this for?

• Data teams drowning in Excel reports from different sources
• Finance and accounting — extract invoices, timesheets, price lists automatically
• ETL pipelines — replace brittle openpyxl scripts that break when a column shifts
• Research and clinical data — reject files that deviate from the expected structure before they corrupt your dataset

You don't need to be a programmer to use grepxcel.

Non-developers: use the browser-based web wizard (pip install "grepxcel[web]" then grepxcel web-wizard data.xlsx) — click cells in the browser to classify them, download the pattern, and run the extraction. No coding required after install. See docs/web-wizard-guide.md for a walkthrough.

Install

Pre-built binaries (no Python required)

Download the latest binary for your platform from the Releases page:

First run on macOS: right-click → Open (bypasses Gatekeeper for unsigned binaries).
First run on Windows: click "More info" → "Run anyway" (SmartScreen warning for unsigned binaries).

Binaries are currently unsigned. Code signing — which eliminates these warnings — is on the roadmap once the project reaches sustainable community support. If grepxcel saves you time, consider supporting it.

via pip (recommended for Python users)

pip install grepxcel

That's all you need to extract data. Optional extras add more capabilities:

Requires Python 3.11+. Works on Linux, macOS, and Windows.

Shell TAB completion (bash/zsh/fish) is included. Add this once to your shell config to activate it:

# bash (~/.bashrc) or zsh (~/.zshrc)
eval "$(register-python-argcomplete grepxcel)"

git clone https://github.com/scpg/grepxcel.git
cd grepxcel
python -m venv .venv
.venv/bin/pip install -e .

How patterns work

A pattern file is a simple spreadsheet (.xlsx or .csv) with four types of rows:

Between START: and END: you tell grepxcel the order to read cells:

START:
  cell:1  IGNORE           ← skip this cell (it's a label)
  cell:1  inv.number       ← read the next cell into "inv.number"
  cell:1  IGNORE
  cell:1  inv.date
END:

Dot notation creates nested output: inv.number → {"inv": {"number": …}}.

Full reference: docs/pattern-file.md covers every instruction, type, and config option in detail.

Describing what cells look like

Each field can have a match pattern that describes what the cell value should look like. You don't need to know regular expressions — here's what most people need:

Tips: Start loose (blank = accept anything), run extract, see what comes out, then tighten. Add config: | ignore.case | yes to match regardless of capitalization.

Under the hood these are standard Python regular expressions. If you already know regex, anything from the Python re syntax works.

Optional quality gates (column A modifiers)

Column A supports order-independent modifiers after the var: or lbl: keyword:

Modifiers combine freely: var:not-null:glob, var:literal:not-empty, etc.

var:not-null   invoice.number   string   INV-\d+   # required regex field
var:glob       sku              string   PROD-*     # glob match
var:literal    status           string   Active     # exact string

CLI commands

# Extract data
grepxcel extract -p pattern.xlsx data.xlsx
grepxcel extract -p pattern.xlsx data.xlsx -o output/     # write JSON to a directory
grepxcel extract -p pattern.xlsx data.xlsx --format csv -o output/   # CSV (single-table)
grepxcel extract -p pattern.xlsx data.xlsx --format xlsx -o output/  # colored Excel report
grepxcel extract -p pattern.xlsx data.xlsx --strict        # fail on any missing field
grepxcel extract -p pattern.xlsx data_dir/ -r              # process a whole directory

# Tools
grepxcel generate-examples                     # create example files to try
grepxcel validate-pattern pattern.xlsx         # check a pattern without extracting
grepxcel lint data.xlsx                        # inspect a file before extraction
grepxcel schema pattern.xlsx -o schema.json    # generate JSON Schema for validation
grepxcel draft data.xlsx                       # AI-draft a starter pattern
grepxcel docs                                  # generate the pattern reference file
grepxcel quickstart                            # guided tutorial in your terminal
grepxcel doctor                                # check your environment is ready

# For AI agents
grepxcel mcp                                   # start MCP server
grepxcel mcp-config                            # print config for Claude / Cursor

Run grepxcel <command> --help for all options.

Python API

import grepxcel

# Get a dict (always available)
result = grepxcel.extract("pattern.xlsx", "data.xlsx")
print(result["po"]["number"])        # "PO-2026"

# Flat tables — skip the {"_source": ..., "data": [...]} envelope
result = grepxcel.extract("pattern.xlsx", "data.xlsx", flat_tables=True)
for row in result["line"]:          # each row dict directly, no unwrapping
    print(row["item"])

# Get DataFrames (pip install 'grepxcel[pandas]' or 'grepxcel[polars]')
frames = grepxcel.extract_df("pattern.xlsx", "data.xlsx")
frames["line"]                       # pandas or polars DataFrame of all table rows
frames["_scalars"]                   # one-row DataFrame of scalar fields

Output format

Fields with dot notation are grouped into nested objects. Tables produce arrays.

{
  "po":     { "number": "PO-2026", "date": "2026-05-01" },
  "vendor": { "name": "Acme Supplies" },
  "line": [
    {
      "data": [
        { "item": "Laptop", "qty": 2, "price": 1200.00, "total": 2400.00 },
        { "item": "Dock",   "qty": 6, "price":   75.00, "total":  450.00 }
      ],
      "footer": { "label": "Grand Total", "value": 3030.00 }
    }
  ]
}

Each table instance is wrapped with {"data": [...], "footer": {...}} so per-instance metadata (source location, header/footer subtotals) survives. If you just want the rows, use --no-source on the CLI or flat_tables=True in the Python API — the wrapper is removed and each table key maps directly to a list of row dicts.

What's new in v0.3.0

• Browser-based wizard — grepxcel web-wizard file.xlsx opens a point-and-click UI to classify cells visually
• Security hardening — CSRF protection on the web wizard, config validation, ReDoS guard on custom match patterns, narrowed exception handling
• Preload fixes — footer rows with no label columns now pre-populate correctly in the wizard

Full history: CHANGELOG.md

Learn more

Support

grepxcel is free and open source. If it saves you time and you'd like to say thanks, you can buy me a coffee — entirely optional and always appreciated.

License

MIT — see LICENSE.