Source Code Install on PyPI Downloads

xlsxgrep

xlsxgrep is a CLI utility designed to search text inside spreadsheet files including XLSX, XLS, XLSM, CSV, TSV, and ODS formats. Built to mimic the behavior of traditional Unix/GNU Linux grep, it bridges the gap between terminal efficiency and tabular data. Whether you need to count matches across a directory of legacy .xls files, extract specific patterns using Python regular expressions, or output clean tab-separated data for your automation scripts, xlsxgrep handles it natively without requiring you to boot up heavy office suites.

Features

  • Grep compatible: supports common grep-style options such as -r, -i, and -c.
  • Batch search: search many spreadsheet files at once, including recursive directory scans.
  • Parallel execution: multi-process search via -j / --jobs (defaults to all available CPU cores) for faster multi-file processing.
  • Regular expressions: Python regex and POSIX extended regular expressions via -E, with fixed-string mode via -F.
  • Supported formats: csv, ods, tsv, xls, xlsx, xlsm.
  • Display-aware values: formatted numeric cells are searched and printed as displayed by XLSX/XLSM, XLS, and ODS spreadsheets; CSV and TSV values remain unchanged.
  • Cross-platform: works on Windows, macOS, BSD, and Linux.
  • Search modes: row mode (-R/--row, default) prints matching rows; column mode (-C/--column) prints whole matching columns vertically. Count mode (-c) always reports matching rows, columns, cells, and strings, regardless of the selected mode.
  • Usable as a module: import xlsxgrep directly into Python code to run searches programmatically and get structured results.

Installation

Install via pip:

pip install xlsxgrep

Or download a standalone installer or portable binary for Windows, macOS, or Linux (.deb/.rpm/.pkg.tar.zst) from the releases page.

Usage

xlsxgrep [OPTION]... PATTERN FILE [FILE]...

See the manual page for full option descriptions, search modes, exit status, and additional examples.

Examples

Search a spreadsheet case-insensitively:

xlsxgrep -i "foo" foobar.xlsx

Count matches and include file names when searching a folder recursively with 4 CPU cores:

xlsxgrep -c -H -r -j 4 "(?i)foo|bar" /folder

Search columns and print matching columns vertically:

xlsxgrep -C "error" report.xlsx

List only files that contain a match:

xlsxgrep -l "invoice" reports/

Show a progress bar while recursively searching a large folder:

xlsxgrep -p -r "error" /folder

Search modes

Row mode (-R, --row, default)
If any cell in a row matches the pattern, the entire row is printed with fields separated by the configured separator.
Column mode (-C, --column)
If any cell in a column matches the pattern, every cell in that column is printed, one per line.

Links