compactxlsx 0.1.0

Write compact XLSX files from pandas DataFrames.

CompactXLSX

Write smaller XLSX files from pandas.

CompactXLSX is a focused, pure-Python writer for exporting pandas DataFrames to minimal XLSX workbooks. It writes OOXML directly, stores repeated text in a shared-string table, and applies maximum ZIP compression by default.

Why CompactXLSX?

• One-line DataFrame export.
• Multiple worksheets from an ordered mapping.
• Small OOXML payload with shared strings.
• Native Excel cells for numbers and booleans.
• Optional compact header style.
• Atomic output replacement and configurable ZIP compression.
• No spreadsheet engine, Java runtime, or Rust toolchain required.

CompactXLSX is intended for large, data-only exports. It is not a replacement for a full spreadsheet authoring library such as XlsxWriter or openpyxl.

Installation

pip install compactxlsx

For local development:

python -m pip install -e '.[test]'

Quick start

import pandas as pd

from compactxlsx import write_xlsx

df = pd.DataFrame(
    {
        "name": ["Alice", "Bob", "Alice"],
        "score": [91.5, 88.0, 95.0],
        "active": [True, False, True],
    }
)

write_xlsx(df, "report.xlsx")

Multiple worksheets:

write_xlsx(
    {
        "Students": students_df,
        "Classes": classes_df,
    },
    "school-report.xlsx",
    index=False,
    header_style=True,
    compression=9,
)

Recompress an existing workbook without changing its OOXML parts:

from compactxlsx import recompress_xlsx

before, after = recompress_xlsx("report.xlsx")
print(f"saved {before - after:,} bytes")

For migration from the original helper, save_excel_compressed() remains as an alias of write_xlsx().

Supported data

CompactXLSX writes missing values as blank cells, booleans as Excel booleans, and finite integers/floats as Excel numbers. Strings are stored in one shared string table. Dates, timedeltas, categories, and other Python objects are currently exported as their string representation. Integers outside Excel's exact IEEE-754 range are stored as text to prevent silent precision loss.

Scope and limitations

• XLSX output only.
• Data-only worksheets; no formulas, charts, images, merged cells, filters, or arbitrary cell formatting.
• Header styling is intentionally limited to one built-in style.
• The complete pandas DataFrame and all unique strings must fit in memory.
• File-size reduction depends on the input. Repeated text generally benefits more than high-cardinality text.
• recompress_xlsx() changes ZIP compression only; it does not remove styles, images, worksheets, or workbook features.

Benchmark

Run the included reproducible benchmark instead of relying on a universal compression claim:

PYTHONPATH=src python benchmarks/benchmark.py --rows 100000

The benchmark reports write time and output size. If openpyxl or XlsxWriter is installed, it includes them as comparison writers.

Development

python -m pip install -e '.[test]'
python -m unittest discover -s tests -v

See CONTRIBUTING.md for contribution guidelines.

License

MIT. See LICENSE.