pyxlsb

pyxlsb is a small, focused Python library for reading Excel Binary Workbook (.xlsb) files — the compact binary variant of the OOXML spreadsheet format that libraries like openpyxl and xlrd cannot parse. Excel writes .xlsb files as a ZIP container of BIFF12 binary records rather than XML, so pyxlsb implements its own low-level BIFF12 record reader and a small set of typed handlers to decode workbook structure, shared strings, and worksheet cell data directly from those bytes.

The API mirrors the shape of xlrd/openpyxl: an open_workbook() call returns a Workbook, get_sheet() returns a Worksheet, and rows() yields plain Cell namedtuples. There is no dependency on Microsoft Excel or any COM/Windows automation layer, which makes it useful in headless data pipelines that need to ingest .xlsb exports — common in finance and enterprise reporting workflows — on Linux or in containers.

What You Get

• open_workbook() / Workbook — opens the .xlsb ZIP container and parses the workbook’s sheet list and shared string table
• get_sheet() / Worksheet — retrieves a single worksheet by index or name and exposes its dimension, columns, and hyperlinks
• rows() iterator — yields each row as a list of Cell(r, c, v) namedtuples, with an optional sparse=True mode to skip fully empty rows
• convert_date() helper — converts Excel’s serial-number date floats into Python datetime objects, handling the Feb 29 1900 leap-year quirk
• A low-level BIFF12Reader and pluggable Handler registry for anyone who needs to decode additional record types

Common Use Cases

• Ingesting .xlsb exports in ETL pipelines - data engineers pulling finance or ERP reports saved in Excel’s binary format into pandas or a warehouse load step
• Headless server-side spreadsheet processing - backend services that need to read .xlsb uploads without installing Excel or a COM automation layer
• Extracting data behind pandas.read_excel(engine="pyxlsb") - pandas uses pyxlsb internally as the engine for .xlsb files
• One-off data recovery from legacy binary workbooks - scripts to convert archived .xlsb files to CSV or JSON for downstream tools that don’t support the format

Under The Hood

Architecture Parsing starts at open_workbook(), which opens the .xlsb file as a ZIP container and hands it to Workbook. Workbook._parse() reads the package relationships, then feeds xl/workbook.bin through a BIFF12Reader to collect the sheet list, and separately loads xl/sharedStrings.bin into a StringTable when present. get_sheet() extracts one worksheet part to a temporary file and constructs a Worksheet, which similarly iterates its own BIFF12Reader to capture dimension, column, and hyperlink records before locating the row-data offset. The reader itself is a generic layered pipeline: a byte-level RecordReader unpacks fixed-width primitives, BIFF12Reader implements the variable-length record-ID/length framing and dispatches each record to a Handler from a registry keyed by record type, and the domain classes (Workbook, Worksheet, StringTable) consume that stream to build their public API. It is a flat, single-threaded module structure with no dependency injection; every downstream class depends directly on BIFF12Reader’s framing logic, so a change there would ripple through the whole library.

Tech Stack pyxlsb has zero third-party runtime dependencies — it relies entirely on the Python standard library: zipfile to open the .xlsb container, xml.etree.ElementTree to read the OOXML relationship files, struct for binary unpacking of BIFF12 primitives, tempfile.TemporaryFile to stage decompressed parts, and collections.namedtuple for lightweight parsed-record objects. There is no compiled extension or async code; everything is synchronous, pure-Python byte parsing. Packaging uses a classic setup.py/setuptools layout rather than a modern pyproject.toml build backend, and the project still declares Python 2.7 compatibility in its classifiers alongside 3.x.

Code Quality The repository has no test directory, no test files, and no CI configuration of any kind, so there is no automated verification of the binary parsing logic. Error handling is minimal: an IndexError is raised for an out-of-range sheet index, a bare exception handler wraps the optional shared-strings load, and unrecognized BIFF12 record types fall through silently to a default Handler that just skips their bytes rather than surfacing anything. There are no type hints anywhere in the codebase (consistent with its Python 2/3 dual-support era) and no linter or formatter configuration. Naming is terse and low-level, matching its role as a binary record decoder rather than application code.

What Makes It Unique pyxlsb’s value isn’t a novel parsing technique — it’s a complete, working reimplementation of Excel’s undocumented BIFF12 binary record grammar at a time when the more popular Python spreadsheet libraries dropped or never had support for the binary .xlsb format. That gap is real enough that pandas registers pyxlsb as its own engine for .xlsb files (pandas.read_excel(engine="pyxlsb")), making this small, low-level library the de facto dependency anywhere a Python data pipeline needs to read Excel’s binary workbook format.