grepxcel

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

pip install grepxcel

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. Same pattern works on next month's invoice, and the one after that.

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. You do need to be comfortable editing a simple spreadsheet to create your first pattern.

Install

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.

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"

# 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 }
    }
  ]
}

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.